Authentication and Access Tokens
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

Authentication Overview

Zocdoc's API uses OAuth 2.0 protocol for secure authentication and authorization. This means you’ll request an access token before making any API calls.

Developer Credentials

You’ll receive unique credentials (client_id and client_secret) for each of Zocdoc’s environments (sandbox and production).

If your app allows user actions, you’ll receive a separate SPA (single-page application) credential set.

Credential Handling Best Practices

Developer credentials are secrets and should be handled in compliance with the Developer Licensing agreement and best practices such as:

Avoid distributing secrets to frontend apps such as browsers or mobile applications.
Avoid hardcoding secrets into codebases.
Avoid storing secrets as plaintext.
Sandbox credentials can be securely distributed to developers for use.
Production secrets should be used only by secure backend services.

All Zocdoc API resource endpoints require a Bearer Authorization header in their request. Which you can retrieve using the client credentials flow.

Header example:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Retrieve Authentication Token

The Client Credentials grant type can be used by client applications to obtain an authentication token.

Authentication tokens from client credentials must not be distributed to browsers or mobile applications.


curl --request POST \
  --url 'https://auth.zocdoc.com/oauth/token' \
  --header 'content-type: application/json' \
  --data '{
    "grant_type": "client_credentials",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "https://api-developer.zocdoc.com/"
  }'

Sandbox

When working with sandbox, use the sandbox access token URL and audience:

access token url: https://auth-api-developer-sandbox.zocdoc.com/oauth/token
audience:https://api-developer-sandbox.zocdoc.com/

There are two ways to get an access token, depending on how your application is set up:

If your app lets users (like patients or providers) take actions without signing in, you will use the Anonymous User Flow.
If your app has signed-in users who need to authorize actions, you will use the Authorization Code Flow.

Authorization Code Flow

Use the Authorization Code Flow when your application requires users to log in and take actions on their own behalf (e.g., booking, managing, or viewing appointments).

Use cases

Use this flow if your app:

Your client application has signed-in users (patients or providers)
You need access to user-specific data or actions
You want to securely authorize users via Zocdoc's login

If the session started anonymously, pass the user's anonymous token to maintain continuity.

Generate a Proof Key for Code Exchange (PKCE)

Zocdoc requires Authentication Code grants to be done with a Proof Key for Code Exchange (PKCE). PKCE is a security enhancement designed to prevent malicious actors from intercepting an authorization code while authorizing a user. To create a PKCE:

Generate a cryptographically-random key known as a code_verifier. Do not use any secret held by the application, as it will be exposed publicly. We recommend generating a random 32-byte array, then encoding it as base64.
Create a SHA256 hash from the code_verifier and encode it as base64. This hash value will be known as the code_challenge. The Zocdoc API only supports "S256" as a code_challenge_method. "plain" is not supported.

const codeVerifier = base64urlEncode(randomBytes(32));
const codeChallenge = base64urlEncode(sha256(codeVerifier));

Step 1: End User Authorization

GET https://auth.zocdoc.com/authorize?
  response_type=code&
  client_id=YOUR_USER_CLIENT_ID&
  redirect_uri=https://YOUR_APP/callback&
  scope=external.appointment.read external.appointment.write offline_access&
  audience=DeveloperApiPatient&
  code_challenge=YOUR_CODE_CHALLENGE&
  code_challenge_method=S256&
  state=STATE_STRING&
  anonymous_token=OPTIONAL_ANONYMOUS_TOKEN&
  login_hint=OPTIONAL_EMAIL

Sandbox

When working with sandbox, use the sandbox auth URL:

auth url: https://auth-api-developer-sandbox.zocdoc.com/oauth/token

Once the user has authenticated, the authorization page will redirect the user to the Redirect URI with an authorization code as the query parameter code.

If access is denied in the authorization page, or another error occurs, the user will be redirected to the redirect URI provided, with query parameters for error and error_description.

Step 2. Exchange the Authorization Code for an Access Token

curl --request POST \
  --url 'https://auth.zocdoc.com/oauth/token' \
  --header 'content-type: application/json' \
  --data '{
    "grant_type": "authorization_code",
    "client_id": "YOUR_USER_CLIENT_ID",
    "code": "AUTH_CODE_FROM_CALLBACK",
    "redirect_uri": "https://YOUR_APP/callback",
    "code_verifier": "ORIGINAL_CODE_VERIFIER"
  }

Token Response Example

{
  "access_token": "ACCESS_TOKEN",
  "refresh_token": "REFRESH_TOKEN",  // only if `offline_access was requested
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "external.appointment.read external.appointment.write"
}

Refresh Tokens

Token Expiration

Access Token = 60 minutes
Refresh Token = 15 days (inactivity), max 30
Login Session = 30 min inactivity, max 1 day

You can use refresh tokens to extend the expiration time of an access token.

To get a refresh token request the offline_access scope during the Authorization Code Flow. The user will be shown a message saying they are approving "Allow offline access" on the authorization page.

curl --request POST \
  --url 'https://auth.zocdoc.com/oauth/token' \
  --header 'content-type: application/json' \
  --data '{
    "grant_type": "refresh_token",
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "client_id": "YOUR_USER_CLIENT_ID"
  }'

Anonymous User Flow

Zocdoc offers an anonymous user flow for provider, provider-location, and reference endpoints without prompting the user to log in. Each user of the client application will receive their own anonymous token.