Token-based Auth

Generates a temporary JSON Web Token (JWT) with a 30-second TTL (Time To Live) for Deepgram APIs.

An temporary token is a secure, authentication credential that provides time-limited access to Deepgram’s APIs. These tokens have a 30 second Time To Live (TTL) and are designed specifically for short-lived, secure API access scenarios, particularly in client-side applications where long-term credential storage is not recommended. Unlike traditional API keys, temporary tokens are ideal for real-time applications requiring secure, temporary access to Deepgram’s services.

Token-based auth flow

Use Cases

Temporary tokens are ideal for client-side/untrusted applications, because they allow clients to directly access the Deepgram API. Normal API keys, to be secure, require proxying traffic through your own servers where the API key is stored.

Direct access to the Deepgram API is particularly useful for client-side/untrusted applications that are more latency-sensitive, like realtime connections.

Implementation Considerations

  1. Create a backend service to generate temporary tokens
  2. Generate tokens only when needed (e.g., at connection start)
  3. Pass the token from your backend to your client
  4. Initiate the Deepgram inference request from your client with the token
  5. Use tokens immediately after generation
  6. Implement proper error handling for expired tokens

Example

To create a JWT token, you can use the /auth/grant endpoint using the Authorization header with the token scheme.

cURL
1curl -X POST https://api.deepgram.com/v1/auth/grant \
2   -H "Authorization: Token YOUR_DEEPGRAM_API_KEY"

Replace YOUR_DEEPGRAM_API_KEY with your Deepgram API Key.

Response

JSON
1{
2  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI2ZDNkMWJiYy0yNmI0LTRlZGQtYjliMy0zNjc3MDM3OTFmZTciLCJle BAiOjE3NDM2MjY2MzQsInN1YmplY3QiOiI2ZDNkMWJiYy0yNmI0LTRlZGQtYjliMy0zNjc3MDM3OTFmZTciLCJzY29wZXMiOlsiYXXyOndyaXRlIl0sInByb2plY3RfY2xhaW1zIjpbInVzYWdlOndyaXRlIl0sImFjY2Vzc29yIjoiMDgy1mM1YTMtNDRlMy00MWVkLThlZWItNDJiOGE1MDkwNjYwIiwiYWNjZXNzb3JfZ2VuZXJhdGlvbiI6MCwiY3JlYXRlZCI6IjIwMjMtMDItYjFUMjE6MTM6NDAuMDE0MzczWiJ9.-nutqvuezqlpxgUiBTKK9niCJeAiy855gBRzop32kCw",
3  "expires_in": 30
4}

To use the JWT token, you can then pass it in the Authorization header of your request to any Deepgram API that supports token-based authentication using the Bearer scheme.

Example

cURL
1 curl -X POST https://api.deepgram.com/v1/listen \
2    -H "Authorization: Bearer YOUR_JWT_TOKEN"

Replace YOUR_JWT_TOKEN with the JWT token you received from the /auth/grant endpoint.

SDK Implementation Examples

1Coming Soon!

FAQ

Why do I get a Forbidden error?

{"err_code":"FORBIDDEN","err_msg":"Insufficient permissions."}

The API key you use for the /auth/grant request needs to have at least Member permissions. To create a key with Member permissions. Login to the Deepgram Console and click on API Keys from the left sidebar. Click the “Create Key” button, then select “Advanced” options and choose “Member” from the permissions dropdown.

Alternatively, you can create a key with Member permissions using the Create Key endpoint.

Can a token have a longer TTL (Time To Live) than 30 seconds?

We currently don’t support modifying the TTL value of temporary tokens.

Can my websocket connection last longer than 30 seconds?

Yes! You only need the temporary token to be valid during the initial websocket connection to Deepgram’s APIs. The websocket connection will then stay open as it would in any other case until you close it.

Which Deepgram APIs can I use with an temporary tokens?

Temporary tokens have usage::write permission for these Deepgram APIs:

These APIs will not work with temporary tokens:

Can I use this token for transcription batch requests?

Yes! You can use this token with batch requests. Just note that due to the short TTL you may need to request a new token before subsequent batch requests. Unless you have latency constraints, you’re likely better off just making the batch request from inside the proxy

Are temporary tokens supported in the Deepgram SDKs?

Not yet, but SDK support is coming soon!

Why should I use temporary tokens over temporary API keys?

  • Fewer Disruptions: Temporary tokens are more resilient to outages, reducing the chances of interruptions to your workflow — especially during planned maintenance or unexpected incidents.
  • Cleaner Deepgram Console Experience: Using temporary tokens means you’ll no longer see pages cluttered with expired API keys. Your usage summary and API keys views will be cleaner and easier to navigate.
  • Smoother Console Performance: Switching to temporary tokens means the Deepgram Console will remain fast and efficient, even as your usage scales.
  • Faster Access: Creating a temporary token is faster than creating an API key, which means faster connection times for Web Sockets.

Can I track the usage from temporary tokens?

Yes! The temporary tokens generated have the same accessor as the API key used to generate them.

What’s Next

Built with