API access requires obtaining OAuth client credentials from Intermezzo. Please contact us to get your credentials.

​
Authentication

Intermezzo API uses OAuth 2 access tokens to authenticate requests. The token is passed in the Authorization header of the request. 
Authorization: Bearer <token>
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

​
Token Request

To obtain an access token, make a POST request to the token endpoint with your client credentials.
Your client_id and client_secret provide access to all your data, so keep them secure. Do not share them publicly by checking them into GitHub or client side code.
curl --request POST \
  --url https://auth.intermezzo.ai/oauth/token \
  --header 'content-type: application/json' \
  --data '{
    "client_id":"RFWrUzk93pUmHCNFuKLto2c239LZKoVO",
    "client_secret":"3wdY-iAPrE8LcYo2X_NhJh38-TemqyRcpGe31LPX9SaGD4HEg6btb30p9b9ddv2C",
    "audience":"https://api.intermezzo.ai",
    "grant_type":"client_credentials"
  }'

​
Token Expiration and Renewal

Access tokens issued through the client credentials flow have a limited lifetime. The lifetime is per client credential and set according to the security policy of the client. The client credentials grant does not support refresh tokens by design. The client can use its credentials (client_id and client_secret) to obtain a new access token.

​
Getting a New Access Token

When your access token expires, simply make a new request to the token endpoint using the same client credentials
Consider implementing automatic token renewal in your application by monitoring the expires_in value and requesting a new token before the current one expires if you need longer sessions for machine-to-machine authentication.

​
User Authentication

For applications that need to authenticate end users (not just machine-to-machine communication), Intermezzo provides several OAuth 2.0 flows designed for different application types and security requirements.

​
Authorization Code Flow

The Authorization Code Flow is the most secure flow for traditional web applications that can securely store client secrets on the server side. 
# Redirect user to authorization endpoint
https://auth.intermezzo.ai/authorize?
  response_type=code&
  client_id=your_client_id&
  redirect_uri=https://yourapp.com/callback&
  scope=openid profile email offline_access&
  state=random_state_value

​
Authorization Code Flow with PKCE

For Single-Page Applications (SPAs) and mobile applications that cannot securely store client secrets, use the Authorization Code Flow with Proof Key for Code Exchange (PKCE). 
# Generate code_verifier (43-128 character random string)
code_verifier="dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"

# Create code_challenge (SHA256 hash of verifier, base64url encoded)

code_challenge="E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"

​
Refresh Tokens

User authentication flows support refresh tokens, which allow applications to obtain new access tokens without requiring users to re-authenticate. 
curl --request POST \
  --url https://auth.intermezzo.ai/oauth/token \
  --header 'content-type: application/json' \
  --data '{
    "grant_type": "refresh_token",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "refresh_token": "v1.MjAxNi0wMS0xM..."
  }'
Refresh tokens are sensitive credentials. Store them securely and never expose them in client-side code or logs. For SPAs, consider using secure storage mechanisms or implementing refresh token rotation.

​
Token Types and Usage

Access Token: Used to authenticate API requests. Include in the Authorization header for protected endpoints. ID Token: Contains user identity information. Used by the client application to establish user sessions and display user profile data. Refresh Token: Long-lived credential used to obtain new access tokens. Only available when offline_access scope is requested.

​
Flow Comparison

Flow TypeApplication TypeClient Secret RequiredRefresh Token Support
Client CredentialsMachine-to-machine✅ Yes❌ No
Authorization CodeTraditional web apps✅ Yes✅ Yes
Authorization Code + PKCESPAs, mobile apps❌ No✅ Yes

​
Best Practices

  • Always use HTTPS for all authentication endpoints
  • Include the offline_access scope to receive refresh tokens
  • Implement proper state parameter validation to prevent CSRF attacks
  • For PKCE, use cryptographically secure random values for code_verifier
  • Store refresh tokens securely and implement proper rotation policies