--- updatedAt: 2026-05-14T14:36:34.000Z agentTools: projectIndex: https://docs.talkdesk.com/llms.txt --- # Obtain a new access token Obtain a new access token # OpenAPI definition ```json { "openapi": "3.0.2", "info": { "title": "Authentication API", "version": "5.12.71", "description": "OAuth and identity endpoints served from the Talkdesk Identity host. Use `{account_name}.talkdeskid.com` as the base URL.", "contact": { "name": "Talkdesk", "url": "https://talkdesk.com" } }, "servers": [ { "url": "https://{account_name}.talkdeskid.com", "description": "United States (td-us-1)", "variables": { "account_name": { "default": "account-name", "description": "The customer's Talkdesk account subdomain." } } } ], "tags": [ { "name": "Authentication", "description": "Authentication API" } ], "paths": { "/oauth/token": { "post": { "operationId": "oauth-token-post", "summary": "Obtain a new access token", "description": "Obtain a new access token", "tags": [ "Authentication" ], "parameters": [ { "name": "Authorization", "in": "header", "description": "Authorization header containing the client authentication, supported via HTTP Basic Auth with the client’s client_id and client_secret. Required if not using a signed JWT assertion (as per the \"private_key_jwt\" mechanism of OpenID Connect)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The access token (and optional refresh token) generated, along with some additional properties about the authorization", "content": { "application/json": { "schema": { "type": "object", "required": [ "access_token", "token_type", "expires_in", "scope" ], "properties": { "access_token": { "type": "string", "description": "The access token" }, "token_type": { "type": "string", "description": "The type of token to be specified in the Authorization header", "default": "Bearer" }, "expires_in": { "type": "integer", "description": "Duration of time (seconds) the access token is granted for" }, "scope": { "type": "string", "description": "A space-separated list of scopes (URL encoded) the client requested access to. If \"scope\" parameter was not provided in the request body parameter, the returned value will be the list of scopes the client granted" }, "refresh_token": { "type": "string", "description": "The refresh token used to obtain another access token. Required only when using \"authorization_code\" and \"refresh_token\" grant types" }, "sid": { "type": "string", "description": "The session ID of the user authenticated during the authorization code flow. Required only when using \"authorization_code\" and \"refresh_token\" grant types" }, "id_token": { "type": "string", "description": "The ID token (OpenID Connect functionality to return information about the authentication performed during the authorization code flow). Required only when using \"authorization_code\" grant type and if \"openid\" scope was included in the \"scope\" parameter provided in the \"/oauth/authorize\" request query parameter\n" } } }, "examples": { "Client Credentials response": { "value": { "access_token": "IsImF1ZCI6Imh0dHBXBp", "token_type": "Bearer", "expires_in": 599, "scope": "openid account:read apps:write contacts:read" } }, "Authorization Code response": { "value": { "access_token": "IsImF1ZCI6Imh0dHBXBp", "token_type": "Bearer", "refresh_token": "NDYyNGUyYTVlNWM3TWEz", "expires_in": 599, "scope": "openid account:read apps:write contacts:read", "sid": "02048a5163b7464867bb0618fd1f03yy", "id_token": "eyJraWQiOiJkYWhwaHVz" } }, "Refresh Token response": { "value": { "access_token": "IsImF1ZCI6Imh0dHBXBp", "token_type": "Bearer", "refresh_token": "NDYyNGUyYTVlNWM3TWEz", "expires_in": 599, "scope": "account:read apps:write contacts:read", "sid": "02048a5163b7464867bb0618fd1f03yy" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "error_description" ], "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } } }, "example": { "error": "invalid_request", "error_description": "Missing grant type" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "error_description" ], "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } } }, "example": { "error": "unauthorized", "error_description": "No refresh token specified" } } } } }, "requestBody": { "description": "The Authentication parameters", "content": { "application/x-www-form-urlencoded": { "schema": { "additionalProperties": true, "discriminator": { "propertyName": "grant_type" }, "type": "object", "required": [ "grant_type" ], "properties": { "grant_type": { "type": "string", "description": "The grant type used for authentication", "enum": [ "client_credentials", "authorization_code", "refresh_token" ] }, "code": { "type": "string", "description": "Authorization code received from the \"/oauth/authorize\" request in the redirect URI. Required only when using \"authorization_code\" grant type" }, "redirect_uri": { "type": "string", "description": "Redirect URI included in the \"/oauth/authorize\" request. Optional, used when grant type is \"authorization_code\"" }, "refresh_token": { "type": "string", "description": "Refresh token previously issued in the authorization code flow. Required only when using \"refresh_token\" grant type" }, "token_type": { "type": "string", "description": "Defaults to jwt. Required only for Service Tokens emission.", "minLength": 1, "maxLength": 32, "enum": [ "opaque" ] }, "expires_in": { "type": "integer", "description": "Lifetime of the requested token, expressed in seconds. Optional, and only applicable when requesting service tokens. Min: 1 day (86400 seconds). Max: 1 year (31556952 seconds)", "minimum": 86400, "maximum": 31556952 }, "scope": { "type": "string", "description": "A space-separated list of scopes (URL encoded) the client is requesting access to. Optional, used only when requesting with \"client_credentials\" and \"refresh_token\" grant types. Whenever a new access token is being issued using \"refresh_token\" grant type, the requested scope must not include additional scopes that were not issued in the original access token and, if omitted, the new access token will be issued with the same scope as was previously issued\n" }, "client_assertion_type": { "type": "string", "description": "The type of signed JWT assertion (it must be \"urn:ietf:params:oauth:client-assertion-type:jwt-bearer\"). Required if not using HTTP Basic Auth in the Authorization header", "enum": [ "urn:ietf:params:oauth:client-assertion-type:jwt-bearer" ] }, "client_assertion": { "type": "string", "description": "Signed JWT assertion (as per the \"private_key_jwt\" mechanism of OpenID Connect). Required if not using HTTP Basic Auth in the Authorization header" } } }, "examples": { "Client Credentials request": { "value": { "grant_type": "client_credentials", "scope": "account:read apps:write contacts:read", "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer", "client_assertion": "eyJraWQiOiJjZTdhNjYy" } }, "Authorization Code request": { "value": { "grant_type": "authorization_code", "code": "TmVlY2IyZlhhYzVmNDAx", "redirect_uri": "https://myapp.example.com/oauth/callback", "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer", "client_assertion": "eyJraWQiOiJjZTdhNjYy" } }, "Refresh Token request": { "value": { "grant_type": "refresh_token", "scope": "account:read apps:write contacts:read", "refresh_token": "NDYyNGUyYTVlNWM3TWEz", "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer", "client_assertion": "eyJraWQiOiJjZTdhNjYy" } }, "Service Token request": { "value": { "grant_type": "client_crendentials", "scope": "account:read apps:write contacts:read", "token_type": "opaque" } } } } } } } } } } ```