OAuth Reference

The Base API supports the industry-adopted standard OAuth 2.0 protocol.

We allow you to use OAuth 2.0 via one of four flows:

Authorization Code Grant - use it if you want to authorize a web application.
Implicit Grant - use it if you want to authorize a user-agent, like a desktop or a mobile application.
Resource Owner Password Credentials Grant - use it if you want to authenticate directly via Base API using resource owner’s password credentials.
Refresh Token Grant - use it to renew an access token when the current one expires.

Retrieve an Authorization Grant

GET /oauth2/authorize

Retrieve an authorization grant. OAuth 2.0 supports two authorization flows:

There is no direct return value. When the resource owner grants an access to your client application Base redirects back to the redirection URI - redirect_uri - and includes an authorization grant, of the type specified by the response_type, in either the query or the fragment of the URI.

Authorization Code Flow

If you follow the Authorization Code Flow the redirection URI will include the following query parameters:

Parameter	Description
`code`	An authorization code, which can be used to obtain an access token.
`state`	The same value as passed to `/oauth2/authorize`

Implicit Flow

If you choose to follow the Implicit Flow the redirection URI will include the following parameters in the URI’s fragment:

Parameter	Description
`access_token`	An access token
`token_type`	A token type. Set to `bearer`.
`expires_in`	An expiration time. Set to one hour in seconds - `3600`.
`refresh_token`	A refresh token.
`scope`	The scope of the access token. It must be present only if the requested scope is different from the default.

JSON Format

Name	Type	Read-only	Mandatory	Description
`response_type`	string	false	true	Authorization grant type requested. If you want to follow Authorization Code Flow, use `code` and if you want to use Implicit Flow, use `token`.
`client_id`	string	false	true	The unique identifier of the client you received from registration.
`redirect_uri`	string	false	true	The URL you registered as the Callback URL during the client registration.
`scope`	string	false	true	A list of space-delimited scopes of the access request. Possible values: `read`, `write`, `profile`
`state`	string	false	false	An opaque string value used to maintain state between the request and callback. The parameter is used to protect against Cross-Site Request Forgery (CSRF).

Allowed for

Agents
Admins

Using cURL

curl -v -X GET https://api.getbase.com/oauth2/authorize?response_type=token&client_id=%24CLIENT_ID&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback&scope=read&state=%24CSRF_TOKEN \

Retrieve an Access Token

POST /oauth2/token

Retrieves an access token. In order to retrieve a bearer access token and a refresh token, a client application makes a request to the token endpoint using the application/x-www-form-urlencoded format.

The following OAuth 2.0 flows are supported:

Notice that every request to the OAuth token endpoint requires client authentication. To authenticate an application use the standard Authorization header using basic authentication scheme, where username is the client_id and password is the client_secret.

The response body will include the following fields:

Parameter	Description
`access_token`	An access token
`token_type`	A token type. Set to `bearer`.
`expires_in`	An expiration time. Set to one hour in seconds - `3600`.
`refresh_token`	A refresh token.
`scope`	The scope of the access token. It must be present only if the requested scope is different from the default.

JSON Format

Name	Type	Read-only	Mandatory	Description
`grant_type`	string	false	true	A grant type. If you want to follow Authorization Code Flow then use `authorization_code` and if you want to use Resource Owner Password Credentials Flow, use `password`.
`client_id`	string	false	true	A unique client identifier
`client_secret`	string	false	true	A unique client secret
`redirect_uri`	string	false	false	The redirection URI that was included in the authorization request. Required if `grant_type` is equal to `authorization_code`.
`scope`	string	false	false	A list of space-delimited scopes of the access request.
`code`	string	false	false	The value of the authorization code you received from the authorization server in the authorization request. Required if `grant_type` is equal to `authorization_code`.
`username`	string	false	false	The resource owner username. Required if `grant_type` is equal to `password`.
`password`	string	false	false	The resource owner password. Required if `grant_type` is equal to `password`.

Allowed for

Agents
Admins

Using cURL

curl -v -X POST https://api.getbase.com/oauth2/token \-H "Content-Type: application/x-www-form-urlencoded" \-H "Authorization: Basic Base64($CLIENT_ID:$CLIENT_SECRET)" \-d 'grant_type=authorization_code&code=$AUTHORIZATION_CODE&redirect_uri=$CLIENT_REDIRECT_URI'

Example response

HTTP/1.1 200 OK
Cache-Control: no-storePragma: no-cache
{  "access_token": "$ACCESS_TOKEN",  "token_type": "bearer",  "expires_in": 3600,  "scope": "read write profile",  "refresh_token": "$REFRESH_TOKEN"}

Revoke a token

POST /oauth2/revoke

Revoke a single access token or a single refresh token and all its related access tokens. This is done in order to notify us that tokens are no longer used so we can clean up security credentials. In order to revoke a token, a client application makes a request to the revocation endpoint using the application/x-www-form-urlencoded format.

Notice that every request to the OAuth revocation endpoint requires client authentication. To authenticate an application use the standard Authorization header using basic authentication scheme, where username is the client_id and password is the client_secret.

Parameter	Description
`token`	The token the client wants to revoke.
`token_type_hint`	A hint about the type of the token. Possible values: `access_token`, `refresh_token`

Allowed for

Agents
Admins

Using cURL

curl -v -X POST https://api.getbase.com/oauth2/revoke \-H "Content-Type: application/x-www-form-urlencoded" \-H "Authorization: Basic Base64($CLIENT_ID:$CLIENT_SECRET)" \-d 'token=$REFRESH_TOKEN&token_type_hint=refresh_token'

Example response

HTTP/1.1 200 OK

Retrieve a CSRF token

GET /oauth2/csrf_token

When you use OAuth 2 either Authorization Code Flow or Implicit Flow, it is highly recommended to pass an opaque string value called state to maintain a state between the request and callback. This parameter is used to protect against Cross-Site Request Forgery (CSRF) attacks. We provide you with an endpoint which returns safe, pseudo-random, anti-CSRF tokens. You can use your own as well. Either way it is highly recommended to use the state parameter during requests.

Parameter	Description
`token`	The token the client wants to revoke.
`token_type_hint`	A hint about the type of the token. Possible values: `access_token`, `refresh_token`

Allowed for

Agents
Admins

Using cURL

curl -v -X GET https://api.getbase.com/oauth2/csrf_token \-H "Accept: application/json" \

Example response

HTTP/1.1 200 OK
Cache-Control: no-storePragma: no-cache
{  "csrf_token": "$ANTI_CSRF_TOKEN",  "generated_at": "2014-09-28T16:32:56Z"}

Authentication

Sync API

Search API

Firehose API

Core APIs

Apps

OAuth Reference

Retrieve an Authorization Grant

Authorization Code Flow

Implicit Flow

JSON Format

Allowed for

Using cURL

Retrieve an Access Token

JSON Format

Allowed for

Using cURL

Example response

Revoke a token

Allowed for

Using cURL

Example response

Retrieve a CSRF token

Allowed for

Using cURL

Example response