Authorization

This section explains how to authorize API requests, generate JWT tokens, and manage usage limits.

You'll learn how to create and include JWTs in request headers, understand Fast and Batch mode limits, and handle rate-limit responses for AI Services.

Get started

AI Services require JSON Web Tokens (JWT) for authorization.

Add the encrypted JWT as the bearer token in each request header. Keep the token active until it expires, and set the expiration to one hour or less for better security.

On your Build Platform App Marketplace page, choose View JWT token in the API keys section to quickly generate and use a token.
Use your CPaaS issued API key and secret to generate a JWT token scoped to a single tenant. Include the JWT token in the Authorization header for all requests:
```
http Authorization: Bearer <JWT_token>
```

Testing

Use this JWT generator to quickly test an endpoint before you implement full JWT generation in your backend.

Rate limits

AI Services follow the rate limits of the Zoom build account and use the Pro rate limit.

For information about Zoom processing rate limits, see Rate limits in Zoom's API reference.

Generate API JWT

To generate an API JWT:

Get your API key and secret.
Follow the guidelines to generate an API JWT for your app.

JWT components

JWTs consist of three core parts: Header, Payload, and Signature. Combine these parts with a period to form a token: 1111111.2222222.3333333.

Header

The Header includes the specification of the signing algorithm and the type of token.

Key	Value
`alg`	`HS256`
`typ`	`JWT`

{
    "alg": "HS256",
    "typ": "JWT"
}

Payload

A JWT payload contains the token’s claims, which includes user information and required metadata.

The payload must include every key.

Keys	Value Description
`iss`	API key
`iat`	Current timestamp
`exp`	JWT expiration date (in epoch format)

{
    "iss": "<YOUR_API_KEY>",
    "iat": 1662147046,
    "exp": 1662152446
}

Signature

To create a JWT signature, encode the header and payload with the API secret using the HMAC SHA256 algorithm.

The signature must include the API_SECRET.

HMACSHA256(
    base64UrlEncode(header) + "." + base64UrlEncode(payload),
    API_SECRET,
);

API JWT example

Here's an example of a valid API JWT: <JWT_TOKEN>

Node.js generate API JWT function

To encode the token, this sample Node.js generate API JWT function uses jsrsasign, an open source cryptographic JavaScript library.

const KJUR = require("jsrsasign");
// https://www.npmjs.com/package/jsrsasign
const iat = Math.round(new Date().getTime() / 1000) - 30;
const exp = iat + 60 * 60 * 2;
const oHeader = { alg: "HS256", typ: "JWT" };
const oPayload = {
    iss: process.env.ZOOM_API_KEY,
    iat: iat,
    exp: exp,
};
const sHeader = JSON.stringify(oHeader);
const sPayload = JSON.stringify(oPayload);
const API_JWT = KJUR.jws.JWS.sign(
    "HS256",
    sHeader,
    sPayload,
    process.env.ZOOM_API_SECRET,
);
console.log(API_JWT);

For additional JWT libraries and examples in more languages, see JWT.io.

Make your first API call

Here is an example to make your first API call with the Scribe API.

In this example, you call the synchronous transcription endpoint. Use your API JWT to call the Scribe API, and replace $TOKEN with your JWT.

curl -X POST https://api.zoom.us/v2/aiservices/scribe/transcribe \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "file": "https://www.mmsp.ece.mcgill.ca/Documents/AudioFormats/WAVE/Samples/AFsp/M1F1-Alaw-AFsp.wav",
    "config": {
      "language": "en-US",
      "output_format": "json"
    }
  }'

You should get a response code of 200 OK and a response body that resembles the code that follows.

{
    "request_id": "AIAPISERVICE_a6ca3e...",
    "duration_sec": 5.869,
    "result": {
        "text_display": "Seed is needed to plant the spring corn.",
        "text_lexical": "seed is needed to plant the spring corn.",
        "segments": [
            {
                "start": 0,
                "end": 2.934,
                "channel": 0,
                "speaker": "Speaker 1",
                "text": "Seed is needed to plant the spring corn.",
                "words": [
                    {
                        "word": "Seed",
                        "start": 0,
                        "end": 0.366
                    }
                    // ...
                ]
            }
        ]
    }
}