# Authentication

The Spoke API uses *OAuth v2.0 client credentials flow* to authenticate requests. You can manage your API access in the Spoke Account Portal at https://account.spokephone.com/login

To authenticate with the Spoke API you need to follow these steps:

1. Create an API key
2. Generate an Access Token
3. Make Authenticated Requests

For more details on the OAuth 2.0 client credentials flow, see the overview at https://auth0.com/docs/flows/concepts/client-credentials

## Create an API key

You must first login as an Administrator to your account in the Spoke Phone Account Portal at https://account.spokephone.com/login. Open the settings page, click `Other`, `Developers`, and add a new `API key`. This is a one time operation.

<img alt="Developer API Screenshot" src="/img/developer_api_screen.png" width="50%" />

Once the "API key" is created, you will be provided with the necessary details (`OAuth 2.0 Client ID`, `OAuth 2.0 client secret`, `Authentication service URL`) needed to create an access token.

## Generate a Token

Once you have created an "API key", the next step is to obtain a bearer token from the Spoke Phone Auth Service at `https://auth.spokephone.com/oauth/token`.  This step requires making an HTTP POST to the Authorization Service URL provided in the step above, with the request body containing an `application/x-www-form-urlencoded` string with the following fields:

| Field Name | Description |
| --- | --- |
| `client_id` | The client id from the Developer API |
| `client_secret` | The client secret from the Developer API |
| `grant_type` | Always `client_credentials` |

A javascript example of this is below:

```javascript
const response = await fetch("https://auth.spokephone.com/oauth/token", {
  method: 'post',
  body: querystring.stringify({
    client_id: "{CLIENT_ID_FROM_DEVELOPER_API}",
    client_secret: "{CLIENT_SECRET_FROM_DEVELOPER_API}",
    grant_type: "client_credentials"
  }),
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
});

const { access_token } = response.json();
```

> Note: The auth token endpoint still supports sending an `application/json` body, however this content type is deprecated in favour of `application/x-www-form-urlencoded`.

## Make Authenticated Requests

To make authenticated API requests, you must provide a valid bearer token in an HTTP Header:

`Authorization: Bearer {access_token}`

Once you have obtained an access token, you must provide this as a Bearer token for all subsequent API requests.

```javascript
const response = await fetch("https://integration.spokephone.com/phonebooks", {
  method: "get",
  headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${access_token}` },
});
```

## Access Token Expiration
Access tokens expire after `3600` seconds (1 hour).  It is up to the developer to implement appropriate refresh logic, by following the same token generation process above.  Note that as flow is a client credentials flow, intended for machine to machine operations, we do not provide a token refresh endpoint. Instead, requesting a new access token using the same client_id/client_secret is sufficient.