# Authentication (/developers/authentication)

There are two methods for authenticating: **personal access tokens** for testing and controlling your own account via the API, and **OAuth** for building integrations where you are operating on behalf of another user.

## Personal Access Tokens [#personal-access-tokens]

Personal access tokens are managed via the SavvyCal interface. To create one, navigate to your [Developer Settings](https://savvycal.com/developers):

![The personal access tokens interface](/images/developers/personal-access-tokens.webp)

Click "Create a token" and give your token a name (it's best to indicate how you plan to use the token). Then, use the `Authorization` header and the `Bearer` realm to authenticate your requests with your Private Key:

```bash
# Example cURL request
curl -H 'Authorization: Bearer pt_secret_XXXXXXXXXXX' https://api.savvycal.com/v1/me
```

## OAuth [#oauth]

We follow the [OAuth 2](https://www.oauth.com) specification for obtaining credentials. Access tokens are short-lived (2 hours) and can be refreshed using the long-lived refresh token issued during the authorization flow.

### Register your application [#register-your-application]

To register an OAuth application, navigate to [Settings > Developers](https://savvycal.com/developers) and click "Create an app" under the **OAuth Applications** section. You'll need to provide the following information:

* **Name**: the name of your application
* **Redirect URIs**: the callback URL(s) to redirect to with a `code` after the authorization flow (e.g. [https://myapp.com/auth/savvycal/callback](https://myapp.com/auth/savvycal/callback))

Once your app is created, you'll receive a client ID and client secret to use in the OAuth flow.

### Requesting access to an account [#requesting-access-to-an-account]

It's generally a good idea to use an OAuth library to handle this process. There are [open source libraries available](https://oauth.net/code/) in most common languages. If you're implementing this flow manually (or just want to understand what going on behind the scenes in one of these libraries), continue on!

To initiate the OAuth flow, send the user to the authorize endpoint and replace `<your-client-id>` and `<your-redirect-uri>` respectively:

```text
https://savvycal.com/oauth/authorize?response_type=code&client_id=<your-client-id>&redirect_uri=<your-redirect-uri>
```

The user will be presented with OAuth screen like this:

![An example of the OAuth screen](/images/developers/oauth-screen.webp)

When the user accepts, they'll be redirected to your redirect URI with a `code` parameter:

```text
https://myapp.com/callback?code=<auth-code>
```

The auth code in the query string can then be exchanged for an access token. Make a `POST` request to `https://savvycal.com/oauth/token` with the following body parameters (form-encoded):

| Parameter       | Value                                       |
| --------------- | ------------------------------------------- |
| `code`          | The auth code from the query string.        |
| `client_id`     | The client ID from your registered app.     |
| `client_secret` | The client secret from your registered app. |
| `grant_type`    | `authorization_code`                        |
| `redirect_uri`  | The redirect URI from your registered app.  |

```http
POST /oauth/token HTTP/1.1
Host: https://savvycal.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json

code=xxxxxxxxx
&client_id=xxxxxxxxx
&client_secret=xxxxxxxxx
&grant_type=authorization_code
&redirect_uri=https://myapp.com/callback
```

The successful response will have a JSON body with the following properties:

| Property        | Description                                                                                                                          |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `access_token`  | A Bearer token to use in the `Authorization` header of API requests.                                                                 |
| `refresh_token` | A refresh token to use to obtain a new access token. You should store this in your database in you need long-term access to the API. |
| `expires_in`    | The number of seconds the `access_token` will remain valid (currently 7200).                                                         |
| `token_type`    | `bearer`                                                                                                                             |

To refresh your access token, send a `POST` request to `https://savvycal.com/oauth/token` with the following body parameters (form-encoded):

| Parameter       | Value                                                          |
| --------------- | -------------------------------------------------------------- |
| `refresh_token` | The refresh token originally issued in the authorization flow. |
| `grant_type`    | `refresh_token`                                                |
| `client_id`     | The client ID from your registered app .                       |
| `client_secret` | The client secret from your registered app.                    |

```http
POST /oauth/token HTTP/1.1
Host: https://savvycal.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json

refresh_token=xxxxxxxxx
&client_id=xxxxxxxxx
&client_secret=xxxxxxxxx
&grant_type=refresh_token
```

The response will be the same shape as the original token response.

### Authenticating requests [#authenticating-requests]

To authenticate your API requests, include the your access token in your `Authorization` header, prefexed with `Bearer` :

```http
GET /v1/me HTTP/1.1
Host: https://api.savvycal.com
Accept: application/json
Authorization: Bearer xxxxxxxxxxxxxxxxxx
```