> ## Documentation Index
> Fetch the complete documentation index at: https://developers.calendbook.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth2 User Authentication

## Overview

OAuth2 allows your application to securely access user data on behalf of the user.

```mermaid theme={null}


sequenceDiagram
    participant User as End User
    participant Partner as Partner Application
    participant AuthServer as Authorization Server<br/>(auth.calendbook.com)
    participant API as Calendbook API

    User->>Partner: Initiates Calendbook connection
    Partner->>AuthServer: Redirects User to Authorization Endpoint
    User->>AuthServer: Authenticates & Grants Consent
    AuthServer-->>Partner: Returns Authorization Code<br/>(via Redirect URI)

    Partner->>AuthServer: Exchanges Authorization Code<br/>for Access & Refresh Tokens
    AuthServer-->>Partner: Issues Access Token + Refresh Token

    Partner->>API: Sends API Request with<br/>Bearer Access Token
    API-->>Partner: Returns Protected Resource<br/>(on behalf of User)
```

***

## Prerequisites

* Obtain your **`client_id`** and **`client_secret`** from the partner portal.
* Configure a **Redirect URI** in the portal — this is where users are sent after authorizing your app.

***

## Authentication Flow

### 1. Redirect the user to the authorization server

Send users to the authorization endpoint where they can log in and approve access.

GET [https://auth.calendbook.com/login](https://auth.calendbook.com/login)

| Parameter       | Description                                                                      |
| --------------- | -------------------------------------------------------------------------------- |
| `client_id`     | The client ID of your application (from Partner Portal).                         |
| `response_type` | Must be set to `code` (Authorization Code flow).                                 |
| `scope`         | Space-delimited list of requested scopes, e.g. `openid+email+phone`.             |
| `redirect_uri`  | The URI where the user will be redirected after consent.                         |
| `state`         | An internal statefW to maintain state between request and callback (CSRF token). |

***

### 2. User login & consent

The user logs in (if not already) and approves the requested scopes.

***

### 3. Receive authorization code

After approval, the user is redirected back to your configured `redirect_uri` with a short-lived `authorization_code`.

***

### 4. Exchange authorization code for access token

Make a **POST** request to the token endpoint: [https://auth.calendbook.com/oauth2/token](https://auth.calendbook.com/oauth2/token)

* Headers:
  `Content-Type: application/x-www-form-urlencoded`

* Body (x-www-form-urlencoded):

```json theme={null}
{
   "grant_type": "authorization_code",
   "client_id": "<partner-client-id>",
   "code": code,
   "client_secret": "<partner-secret>",
   "redirect_uri": "<partner-redirect-url>"
}
```

* Response Body:
  * access\_token
  * refresh\_token

***

### 5. Call the API

* Use the `access_token` in the Authorization header

***

### 6. Refresh token

When the access\_token expires, request a new one with the refresh\_token:

* POST [https://auth.calendbook.com/oauth2/token](https://auth.calendbook.com/oauth2/token)

* Headers:
  `Content-Type: application/x-www-form-urlencoded`

* Body (x-www-form-urlencoded):

```json theme={null}
{
   "grant_type": "refresh_token",
   "client_id": "<partner-client-id>",
   "refresh_token": "<refresh-token>",
   "client_secret": "<partner-secret>",
 }
```

Response includes a new `access_token`