OAuth 2.0¶

Introduction¶

Speakap clients use OAuth 2.0 to authenticate themselves with the API. In order to perform an API request, an access token is required. This document describes how to obtain an access token and provides a small example in how to use it.

Acquiring access and/or refresh tokens¶

Initiating the OAuth2 authorization flow¶

In order to retrieve an access token that is tied to a specific user profile, you need to initiate the OAuth 2.0 authorization flow through a redirect. The user will then be given the choice to accept the authorization after which he or she will be redirected back to your application. When the user is redirected back to your application, you will receive an authorization code (assuming the user accepted the authorization) which you can use to request the access token through a server-to-server request to the Speakap authenticator.

But before you can do anything, it is important that you know the subdomain (and later the EID) of the Speakap network that you will be using to authenticate against. How you choose the network to use is outside of the scope of this document. Now, assuming you have the right information, let’s start by redirecting the user to the authorization flow.

The user should be redirected to the following URL:

https://<network-subdomain>.speakap.com/auth?client_id=...&redirect_uri=...&scope=...&state=...

The various parameters in this URL have the following meaning:

Once the user has accepted or denied the authorization request, he or she will be redirected back to your application to the given redirect_uri. At this point you will always receive the given state parameter that you specified yourself and which you can use to verify that you initiated the request (as well as to identify the returning user). In addition, you will receive a code parameter if the user accepted your authorization request which contains the authorization code that you can use to request your access token. If the user declined the request (or if an error occurred), you will receive an error parameter and optionally an error_description parameter.

The possible values of the error parameter, as well as other, more in-depth information, can be found in the OAuth 2.0 RFC.

Once you are in possession of an authorization code and have verified the state was correct, you can retrieve your access token using the following request:

Using the access token¶

To perform an API request, clients need to pass along a valid access token to authenticate themselves with the Speakap API. This can be done either by including an Authorization Bearer header, or by passing the access_token parameter with every API request.

For example, assuming your access token is “f4k3_t0k3n_str1ng”, you can perform the following request:

$ curl https://api.speakap.io/networks/053ecd475a000f30/ -H "Authorization: Bearer f4k3_t0k3n_str1ng"
{
    "_links": {
        "self": {
            "href": "/networks/053ecd475a000f30/"
        },
        "emblem": {
            "href": "/networks/053ecd475a000f30/messages/053f0e65ab05a950/"
        },
        "userProfile": {
            "href": "/networks/053ecd475a000f30/users/053f0e64ac194e3d/"
        }
    },
    "type": "network",
    "EID": "053ecd475a000f30",
    "name": "Speakap",
    "subdomain": "speakap",
    "description": "",
    "emblemThumbnailUrl": "https://speakap.speakap.com/files/053f0e65ab05a950/thumbnail",
    "subscription": { "type": "premium", "since":"2013-09-18T17:54:37.550+00:00" }
}

Or alternatively:

$ curl https://api.speakap.io/networks/053ecd475a000f30/?access_token=f4k3_t0k3n_str1ng
{ ... }

Retrieving tokens using user credentials¶

This method of retrieving access and refresh tokens is only supported for first-party Speakap applications. The access token you will receive is ready to use (see Using the access token), but only valid for a short amount of time (typically one hour), so care needs to be taken to refresh it before it expires (see Refreshing access token).

Refreshing access token¶