Authorization Code - JWT

Access token request - get a new access token


Europe (EU) and Canada (CA) Base URLs

EU - https://{talkdesk-account-name}

CA - https://{talkdesk-account-name}


Access and Registration


Client Authentication

The requests made to the token service must be authenticated using a signed JWT assertion (as per the private_key_jwt mechanism of OpenID Connect):

require 'jwt'
require 'securerandom'

key = '<client_private_key>'

pem_key = key.scan(/.{1,64}/).tap do |lines|
  lines.unshift "-----BEGIN PRIVATE KEY-----"
  lines.push "-----END PRIVATE KEY-----"

private_key = pem_key

payload = 
    "jti": SecureRandom.uuid,
    "iss": "<client_id>",
    "sub": "<client_id>",
    "aud": "https://<account_name>",
    "exp": + 5*60

token = JWT.encode payload, private_key, '<client_key_algorithm>', {"kid": "<client_key_id>"}
package com.talkdesk.example;

import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;

import java.time.Instant;
import java.util.Base64;
import java.util.Date;
import java.util.UUID;

public class GenerateClientAssertion {

    public static void main(String... args) throws NoSuchAlgorithmException, InvalidKeySpecException, IOException {
        String key = "<client_private_key>";

        // Replace EC with ECDSA if BouncyCastle is enabled
        PrivateKey privateKey = KeyFactory.getInstance("EC")
                .generatePrivate(new PKCS8EncodedKeySpec(Base64.getDecoder().decode(key)));

        String token = Jwts.builder()
                .setHeaderParam("kid", "<client_key_id>")
                .setIssuedAt(new Date())
                .signWith(SignatureAlgorithm.<client_key_algorithm>, privateKey)

# Requires the 'PyJWT' and 'cryptography' packages to be installed

import uuid
import jwt
from datetime import datetime, timedelta

# Client Private Key
CLIENT_PRIVATE_KEY = "<client_private_key>"


# JWT Headers
headers = {"kid": "<client_key_id>"}

# JWT Payload
payload = {"iss": "<client_id>",\
    "sub": "<client_id>",\
    "aud": "https://<account_name>",\
    "jti": str(uuid.uuid4()),\
    "exp": datetime.utcnow() + \
    "iat": datetime.utcnow()}

# Signed JWT 
jwt_token = jwt.encode(payload, CLIENT_PRIVATE_KEY, algorithm = "<client_key_algorithm>", headers = headers)
  '[clj-time.core :as time]
  '[buddy.sign.jwt :as jwt]
  '[buddy.core.keys :as keys])

(def token 
    {:jti (str (java.util.UUID/randomUUID))
     :iss "<CLIENT_ID>" 
     :sub "<CLIENT_ID>" 
     :aud "" 
     :exp (time/plus (time/now) (time/minutes 5)) 
     :iat (time/now)}
    (keys/private-key "<CLIENT_PRIVATE_KEY_FILE>")
    {:alg :es256
     :kid "<CLIENT_KEY_ID>"}))
// Requires the 'jsonwebtoken' and 'uuid' packages to be installed
var jwt = require('jsonwebtoken');
var uuid = require('uuid/v4');

var private_key = '<client_private_key>'
private_key = "-----BEGIN PRIVATE KEY-----\n" + private_key + "\n-----END PRIVATE KEY-----"

var header = {
  kid: '<client_key_id>'

var payload = {
  iss: '<client_id>',
  sub: '<client_id>',
  aud: 'https://<account_name>',
  jti: uuid(),
  exp: Math.floor( / 1000) + 300,
  iat: Math.floor( / 1000)

token = jwt.sign(payload, private_key, {header: header, algorithm: '<client_key_algorith>'})


Signed JWT - Expiration

You will get an invalid_client error message if your signed JWT has expired.

In the example above, the signed JWT expires after five minutes. If you wish to have a signed JWT with a longer expiration date, you can change it via the exp and/or setExpiration variables.

Body Response - Schema

200 (the access token - and optional refresh token - generated, along with some additional properties about the authorization)

access_tokenstringthe access tokenyes
token_typestringThe type of token to be specified in the authorization header. Default: Bearer.yes
expires_inintegerduration of time (seconds) the access token is granted foryes
scopestringA space-separated list of scopes (URL encoded) the client requested access to. If the "scope" parameter is not provided in the request body parameter, the returned value will be the list of scopes the client granted.yes
refresh_tokenstringThe refresh token used to obtain another access token. Required only when using "authorization_code" and "refresh_token" grant
sidstringThe refresh token used to obtain another access token. Required only when using "authorization_code" and "refresh_token" grant
id_tokenstringThe ID token (OpenID Connect functionality to return information about the authentication performed during the authorization code flow). Required only when using the "authorization_code" grant type and if "openid" scope was included in the "scope" parameter provided in the "/oauth/authorize" request query

400 (bad request), 401 (unauthorized)




If you have questions or technical issues, please open a ticket using this form.

Access Token Request

Click Try It! to start a request and see the response here!