Copy page

Guides

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.

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:

Code
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.

Code
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.