ZoomInfo API OAuth Authentication

Partners are responsible for creating applications that can handle the two parts of the OAuth authentication flow: authorization and token exchange. ZoomInfo API requires all applications to provide Proof Key for Code Exchange (PKCE) along with other standard OAuth client details for additional security.

Proof Key for Code Exchange (PKCE)

The Proof Key for Code Exchange (PKCE) is an OAuth 2.0 extension that secures the Authorization Code flow for public clients by replacing fixed secrets with a dynamic mechanism. It works by having the client generate a random Code Verifier and a hashed Code Challenge at the start of the flow. The Code Challenge is sent to the Authorization Server (Okta), which stores it temporarily. After authentication, the client exchanges the authorization code for tokens by sending the original Code Verifier. The server hashes this verifier and, if it matches the stored challenge, issues the tokens, ensuring secure authorization.

Generating the `code_verifier` and `code_challenge`

A Code Verifier is a random, securely stored string used during the token exchange and The Code Challenge is a hashed version of the Code Verifier, sent to the Authorization Server to validate the token request.

Authorization

The client application must redirect its users to authenticate through ZoomInfo Login, which uses the Authorization server (Okta) to verify, authenticate, and provide a token.

Prerequisites

Partners must ensure the following query parameters are appended to the ZoomInfo login URL:

Parameter	Required	Description
`state`	✅	A randomly generated UUID to maintain state between the request and callback
`code_challenge`	✅	A SHA-256 generated message digest used for PKCE
`redirect_uri`	✅	The callback URI where the authorization response will be sent
`client_id`	✅	The Okta application ID
`scopes`	❌	Required scopes for access. If not provided, access will be granted to all scopes registered upon app creation

Note on Scopes: Multiple scopes are separated by spaces and must be URL encoded. Best practice is to exclude scopes from the login URL. When application access needs to be split across multiple sets of scopes, we recommend creating a separate application.

Example Login URL

The login URL follows this format:
https://login.zoominfo.com/ with the required query parameters appended.

Token Exchange

The client application makes a request to exchange the code for tokens, sending the Code Verifier instead of a fixed secret. The Authorization Server hashes the Code Verifier and compares it to the stored hashed value. If they match, the Authorization Server returns the tokens.

Callback Parameters

The callback should accept the following request parameters:

code: The authorization code received in the query parameters
state: The state parameter to validate the request

Token Exchange Steps

1. Create the Authorization Header

Create a Basic Authentication header by encoding the client ID and client secret in Base64 format. The format should be Basic <encoded_credentials> where the credentials are clientId:clientSecret.

2. Construct the Request Body

Prepare the request body with the following parameters:

code: The authorization code received from the callback
grant_type: Set to "authorization_code"
redirect_uri: The same redirect URI used in the authorization request
code_verifier: The original code verifier generated during PKCE

3. Make a POST Request to Okta

Endpoint: https://okta-login.zoominfo.com/oauth2/default/v1/token

Headers:

Authorization: Basic <clientAuth>
Content-Type: application/x-www-form-urlencoded

Expected Response

The response will contain:

Token Type	Validity	Description
Access Token	24 hours	Used for API authentication
ID Token	24 hours	Contains user identity information
Refresh Token	Rotated after use	Used to obtain new access tokens
Scopes		The scopes granted to the tokens

Token Rotation

🔄 Important: The refresh token will be rotated after each use. There is a 30-second grace period during which the previous refresh token remains valid to allow seamless token renewal.

Implementation Overview

ZoomInfo OAuth Integration

Open Recipe

The authentication implementation involves two main components:

Authorization Flow (Generating ZoomInfo Login URL)

The authorization process requires:

Generate Code Verifier: Create a random 32-byte string, encode it in Base64, and apply URL-safe transformations (replace / with _, + with -, and remove = padding).
Generate Code Challenge: Hash the code verifier using SHA-256, encode the result in Base64, and apply the same URL-safe transformations.
Store PKCE Data: Create a PKCE record containing both the code challenge and code verifier, then store it temporarily using a randomly generated state UUID as the key.
Build Login URL: Construct the ZoomInfo login URL with all required query parameters including state, code challenge, redirect URI, client ID, and optional scopes.

Token Exchange Flow

The token exchange process involves:

Retrieve PKCE Data: Use the state parameter to retrieve the stored code verifier from your temporary storage and remove it to prevent reuse.
Create Authentication: Generate a Basic Authentication header by Base64-encoding the client ID and secret combination.
Prepare Request: Build the token exchange request body with the authorization code, grant type, redirect URI, and code verifier.
Exchange Tokens: Send the POST request to Okta's token endpoint and receive the access token, ID token, refresh token, and granted scopes.

Security Best Practices

🔐 Always use HTTPS for redirect URIs and token exchanges
🔄 Implement proper token rotation handling with the 30-second grace period
🗂️ Store code verifiers securely and remove them after use
🎯 Use minimal scopes required for your application
🔍 Validate state parameters to prevent CSRF attacks

For additional support and documentation, contact your ZoomInfo API representative.