Token-Based Auth

A 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.

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.

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

Response

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

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

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 recommend keeping your TTL as short as possible for security reasons, but for certain cases (e.g. mobile) a longer TTL may be required. In this case, pass ttl_seconds : your_ttl in the request body. The max TTL supported is 3600 seconds (1 hour).

Can my websocket connection last longer than the token’s TTL?

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 a temporary token?

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

• /listen REST API - Speech to Text
• /listen WebSocket API - Speech to Text
• /speak REST API - Text to Speech
• /speak WebSocket API - Text to Speech
• /read REST API - Text Intelligence
• /agent WebSocket API - Voice Agent

These APIs will not work with temporary tokens:

• The collection of Management APIs

Can I use this token for speech-to-text pre-recorded requests?

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

Are temporary tokens supported in the Deepgram SDKs?

Yes. The Deepgram SDKs support token-based authentication. Please refer to the SDKs Feature Matrix page for more information.

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 WebSockets.

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

• For more information, refer to the Token-based Authentication API Reference.