# Authentication and Access Tokens

## Authentication Overview

Zocdoc's API uses [OAuth 2.0](https://oauth.net/2/) 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](https://www.rfc-editor.org/rfc/rfc6749#section-4.4) 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](https://www.rfc-editor.org/rfc/rfc6749#section-4.1) 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](https://www.rfc-editor.org/rfc/rfc7636)). 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](https://www.rfc-editor.org/rfc/rfc6749#section-1.5)

### 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](#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.

Use cases
Use this flow if your app:

- Lets users search for providers or locations anonymously
- Doesn't have user login
- Wants to defer login until later (e.g., at booking time)


### Request an Anonymous Access Token


```
curl --request POST \
  --url 'https://api-developer-sandbox.zocdoc.com/v1/token/anonymous-user' \
  --header 'Authorization: Bearer YOUR_AUTHORIZATION_TOKEN' \
  --header 'content-type: application/json' \
  --data '{ "app_client_id": "YOUR_CLIENT_ID" }'
```

Optional: Upgrade to Logged-In User
If the user logs in later, you can pass the anonymous token to the Authorization Code Flow so Zocdoc can link their anonymous session with their authenticated account.

## Best Practices

1. Cache your access token to avoid generating too many.
2. Use separate credentials for sandbox and production.
3. Keep your credentials secure—treat them like passwords.