⚠️ Before you start, make sure you've reviewed the prerequisites in Read AI API and MCP Overview.
This guide explains how to get credentials to authenticate with the Read AI API programmatically. The Read AI API uses OAuth 2.1 with dynamic client registration.
Note: Read AI doesn't issue static or long-lived API keys for the Read AI API. Instead, you authenticate with short-lived OAuth access tokens, which you renew with a refresh token as described below. (The Generate API key option on the Zapier integration page creates a key for connecting Read to Zapier; see Getting Started with Zapier.)
Read supports the Authorization Code grant with refresh tokens for obtaining and renewing access tokens.
To call the API:
- Register an OAuth 2.1 client using dynamic client registration.
- Obtain an authorization code via the Authorization Code flow.
- Exchange the authorization code for access and refresh tokens.
- Use the access token to make API requests.
- Refresh the access token as needed using the refresh token.
Tip: We recommend adding | jq . to the end of your curl requests to make the output easier to read. |
Step 1: Register your OAuth client
Do this step from a command-line interface, using a tool such as curl.
Important: Save your client_id and client_secret immediately. The client_secret is sensitive and should be stored securely.
Example API call
curl -X POST https://api.read.ai/oauth/register \
-H "Content-Type: application/json" \
-d '{
"client_name": "My Analytics Dashboard",
"redirect_uris": ["https://api.read.ai/oauth/ui"],
"grant_types": ["authorization_code", "refresh_token"],
"response_types": ["code"],
"scope": "openid email offline_access profile meeting:read mcp:execute",
"token_endpoint_auth_method": "client_secret_basic"
}'You can use any value you like for client_name. Leave all other details unchanged, unless you want your client to send its credentials in the request body (see Client authentication method below).
Example response
{
"client_id": "test_id",
"client_name": "My Analytics Dashboard",
"client_secret": "super_secret",
"redirect_uris": ["https://api.read.ai/oauth/ui"],
"token_endpoint_auth_method": "client_secret_basic",
"allowed_cors_origins": [],
"grant_types": [
"authorization_code",
"refresh_token"
],
"scope": "openid email meeting:read offline_access profile mcp:execute",
"audience": [
"https://api.read.ai/v1/meetings",
"https://api.read.ai/mcp"
],
"registration_client_uri": "https://authn.read.ai/oauth2/register",
"registration_access_token": "access_token"
}Remember to save your client_id and client_secret. You can't retrieve them again later.
Client authentication method
The token_endpoint_auth_method you set when you register decides how your app must send its client ID and secret to the token endpoint in Steps 3 and 5. Two methods are supported:
-
client_secret_basic(used in the example above): send the client ID and secret in an HTTP BasicAuthorizationheader. -
client_secret_post: sendclient_idandclient_secretas form fields in the request body. To use this method, set"token_endpoint_auth_method": "client_secret_post"in your registration request.
If your app sends credentials a different way than the method you registered with, the token endpoint rejects the request with 401 Unauthorized. To switch methods, register a new client with the method you want and complete Steps 2 and 3 again. Tokens from one client don't work with another client's credentials.
Step 2: Obtain an authorization code
This step happens in a web browser, from the Read AI OAuth page.
Start the OAuth flow
Go to https://api.read.ai/oauth/ui and:
- Input your client ID and client secret from your dynamic client registration.
- Check that the redirect URI is already filled in as
https://api.read.ai/oauth/ui. - Click Start OAuth Flow when you're ready.
Sign in to Read AI
If you aren't already logged in to Read AI in your browser, you'll be sent to the Read AI sign-in page. Sign in with your account.
All single sign-on (SSO) options should work, but some users have reported that they weren't automatically sent back to the OAuth consent screen after logging in. If this happens, restart the process at https://api.read.ai/oauth/ui. Because you're already signed in, it should skip the sign-in step.
Consent screen
Click Allow Access to grant all the listed scopes to your access token.
Authorization code screen
You now have your authorization code! In the next step, you'll exchange it for an access token and refresh token. The easiest way is to click Copy Command, then paste the command into your command-line interface.
Step 3: Exchange authorization code for tokens
Go back to your command-line interface and run the command you copied at the end of the last step. Copy and securely save the access_token and refresh_token values.
Example request
curl -X POST https://authn.read.ai/oauth2/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -H "Authorization: Basic $(echo -n 'REDACTED' | base64)" \ -d "grant_type=authorization_code" \ -d "code=REDACTED" \ -d "redirect_uri=https://api.read.ai/oauth/ui" \ -d "code_verifier=REDACTED"
Example response
{
"access_token": "REDACTED",
"expires_in": 599,
"id_token": "REDACTED",
"refresh_token": "REDACTED",
"scope": "openid profile email meeting:read mcp:execute offline_access",
"token_type": "bearer"
}Step 4: Use the access token to make API calls
You can now authenticate requests to the REST API by including the access token in the Authorization header as a Bearer token.
Example request
curl -X GET "https://api.read.ai/oauth/test-token-with-scopes" \ -H "Authorization: Bearer ACCESS_TOKEN"
This is a simple endpoint for testing. For the full list of API endpoints and other specification details, see API Reference.
Step 5: Refresh the access token as needed
Access tokens expire after 10 minutes and must be refreshed to continue making API requests.
To get a new access token, send a request to the OAuth token endpoint using the refresh_token grant.
Token lifetimes
- Access token: 10 minutes.
- Refresh token: about 6 months (4,380 hours, or 182.5 days).
- Grace period for a replaced refresh token: after a refresh, the previous refresh token keeps working for up to 10 minutes after the new one is issued, or for 5 more uses, whichever comes first. After that, it's rejected.
Important: Refresh tokens are rotated on every use. The token endpoint returns a new refresh token each time you exchange one. You must securely persist the new refresh token and discard the previous one. The grace period exists to handle concurrent requests and failed refresh calls, not for ongoing use of the old token.
Example request (client_secret_basic)
curl -X POST https://authn.read.ai/oauth2/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-u "CLIENT_ID:CLIENT_SECRET" \
-d "grant_type=refresh_token" \
-d "refresh_token=YOUR_REFRESH_TOKEN"Example request (client_secret_post)
Use this format only if you registered your client with "token_endpoint_auth_method": "client_secret_post".
curl -X POST https://authn.read.ai/oauth2/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=refresh_token" \
-d "refresh_token=YOUR_REFRESH_TOKEN" \
-d "client_id=CLIENT_ID" \
-d "client_secret=CLIENT_SECRET"Troubleshooting tips
- Save the new refresh token from every refresh response right away, in persistent storage, and discard the old one.
- Let only one process refresh at a time. If several workers share the connection, have them read from one token store and lock around the refresh.
- If a refresh call fails with a 5xx error or times out, retry immediately with the same refresh token. Don’t wait for your next scheduled refresh. The old refresh token only keeps working for up to 10 minutes after a new one is issued, or 5 more uses, whichever comes first.
-
Getting 401 Unauthorized when refreshing? Check that you're sending the client ID and secret the way your client was registered: in a Basic
Authorizationheader forclient_secret_basic, or as form fields forclient_secret_post. Also make sure you're using the newest refresh token, and the client ID and secret from the same registration that issued it. - Refresh tokens expire after about 6 months. If your refresh token has expired, repeat Steps 2 and 3 to get new tokens.