OAuth Requests

Client Authentication

Registered OAuth applications are assigned a unique Client ID (client_id) and unique Client Secret (client_secret).

By sending the client_id and the client_secret, you are letting Base API know which application is accessing the API. Only requests to the Authorization Server require client credentials.

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

Authorization: Basic Base64($CLIENT_ID:$CLIENT_SECRET)

The way to do this using a tool like curl is to use the -u or --user flag, which is used for passing authentication information in the form of username:password. For example, the Resource Owner Password Credentials flow requires the client credentials and the resource owner’s credentials in order to obtain an access token. The example below shows how to make the request.

$ curl -v -X GET https://api.getbase.com/oauth2/token \
       -u "$CLIENT_ID:$CLIENT_SECRET" \
       -d "grant_type=password" \
       -d "username=$USERNAME" \
       -d "password=$PASSWORD"

Authorization Code Flow

Authorization Code Flow - Three Legged - is the most secure authentication flow, and should be utilized when possible. This flow is optimized for web applications and requires your client application to handle redirections.

Your client application directs a resource owner to the Base Authorization Server in order to grant authorization. In that case, the client application doesn’t need to store or even directly request any resource owner’s credentials.

The flow includes the following steps: Authorization Request and Token Request.


Authorization Request

In the first step, your client application directs a resource owner to the OAuth 2.0 authorization endpoint and includes the following query parameters:

  • response_type - Must be set to code.
  • client_id - The same unique identifier of the client you received from registration.
  • redirect_uri - The same URL you registered as Callback URL during the client registration.
  • state - (optional) A string used to maintain state between the request and callback. The parameter is used to protect against Cross-Site Request Forgery (CSRF).
https://api.getbase.com/oauth2/authorize
      ?client_id=$CLIENT_ID
      &response_type=code
      &redirect_uri=$CLIENT_REDIRECT_URI
      &state=$STATE

At this point, Base will ask the resource owner to log in (if necessary) and to authorize the application with the client_id. They can choose to deny the authorization request as well. Afterwards, Base will redirect the resource owner back to the redirection URI provided earlier. The redirection URI will include the authorization code within the code query parameter and the state value given in the previous request. The authorization code is valid for 10 minutes.

https://example.com/oauth/callback?code=$AUTHORIZATION_CODE&state=$STATE

Token Request

The last step to follow is to request an access token using the authorization code you received from the previous step.

In order to obtain an access token, perform a POST request to the /oauth2/token token endpoint with the grant_type set to the authorization_code, the redirect_uri set to the same value as in the previous step and the code set to the value of the authorization code you received from the last call. Remember that every request to the OAuth 2.0 token endpoint requires client authentication.

curl -X POST -v https://api.getbase.com/oauth2/token \
     -u "$CLIENT_ID:$CLIENT_SECRET" \
     -d "redirect_uri=$CLIENT_REDIRECT_URI" \
     -d "grant_type=authorization_code" \
     -d "code=$AUTHORIZATION_CODE"

If this request is successful, the Authorization Server will authenticate the client, validate the authorization code and the redirection URI, and will respond back with a JSON payload containing an access token, a refresh token, a token type set to bearer and an expiration time set to one hour.

{
  "access_token": "$ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "read write profile",
  "refresh_token": "$REFRESH_TOKEN"
}

Implicit Flow

The Implicit Flow - Two Legged - is optimized for user-agent, mobile or desktop applications, such as JavaScript-based browser clients, and requires your client application to handle redirections.

Your client application directs a resource owner to Base Authorization Server in order to grant authorization. In that case, the client application does not need to store or even ask about any resource owner’s credentials directly.

Both Code Authorization and Implicit flows are very similar. The difference is that when using Implicit flow, there is no need to make an additional request to the OAuth 2.0 token endpoint to get an Access Token, since it’s returned when the user agent is redirected to the redirection URI.


Authorization Request

The Implicit flow requires only a single step where your client application directs a resource owner to the OAuth 2.0 authorization endpoint, and includes the following query parameters:

  • response_type - Must be set to token.
  • client_id - The same unique identifier of the client you received from registration.
  • redirect_uri - The same URL you registered as Callback URL during the client registration.
  • state - (optional) A string used to maintain state between the request and callback. The parameter is used to protect against Cross-Site Request Forgery (CSRF).
https://api.getbase.com/oauth2/authorize
      ?client_id=$CLIENT_ID
      &response_type=token
      &redirect_uri=$CLIENT_REDIRECT_URI
      &state=$STATE

At this point, Base will ask a resource owner to log in (if necessary) and to authorize the application with the client_id. They can choose to deny the authorization request, too. Afterwards, Base will redirect the resource owner back to the redirection URI provided earlier. The redirection URI will include an access token, an expiration time set to one hour, a token type set to bearer and the state value given in the previous request. The access token part is returned in the URI fragment.

https://example.com/oauth/callback
      #access_token=$ACCESS_TOKEN
      &token_type=bearer
      &expires_in=3600
      &state=$STATE

Resource Owner Password Credentials Flow

Resource Owner Password Credentials flow - Two Legged - is the simplest and least-secure authentication flow that Base supports. The flow is optimized for cases where you may want to authenticate directly via Base API using the resource owner’s password credentials. This flow requires a lot of trust in the client application.


Token Request

The Resource Owner Password Credentials flow requires only a single step, where your client application performs a POST request to the /oauth2/token token endpoint with the grant_type set to password and including the resource owner’s credentials, in order to obtain an access token. Remember that every request to the OAuth 2.0 token endpoint requires client authentication.

curl -X POST https://api.getbase.com/oauth2/token \
     -u "$CLIENT_ID:$CLIENT_SECRET" \
     -d "grant_type=password" \
     -d "username=$USERNAME" \
     -d "password=$PASSWORD"

If the Authorization Server authenticates the client and resource owner’s credentials, it will respond back with a JSON payload containing an access token, a refresh token, a token type set to bearer, and an expiration time set to one hour.

{
  "access_token": "$ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "read write profile",
  "refresh_token": "$REFRESH_TOKEN"
}

Accessing Protected Resources

To access protected resources, the resource owner needs to supply the Access Token in a format described in the industry-adopted standard OAuth 2.0: Bearer Token.

To authenticate to the API, use the standard Authorization header using the Bearer authentication scheme to transmit the access token. The syntax for the Authorization header is shown below.

Authorization: Bearer $ACCESS_TOKEN

The way to do this using a tool like curl is to use the -H flag, which is used to include an extra header in the request when sending HTTP to a server. In our case, -H "Authorization: Bearer $ACCESS_TOKEN". For example, to authenticate and retrieve all contacts execute:

$ curl -v -X GET https://api.getbase.com/v2/contacts \
       -H "Accept: application/json" \
       -H "Authorization: Bearer $ACCESS_TOKEN"

Requests with no Authorization header will be rejected with a 401 status code.


Refreshing an Access Token

Every single access token issued via the OAuth 2.0 token endpoint has a finite lifetime of one hour. The Base Authorization Server provides you with an additional token called a Refresh Token, via refresh_token field.

Requests with an expired access token will be rejected with a 401 status code. You need to use the Refresh Token credentials in order to obtain a new access token. Refresh tokens are never sent to Resource Servers. They are intended to be used by the Authorization Server.

When your application receives a refresh token, it is important to store that refresh token for future use. If your client application loses the refresh token, you will have to prompt the resource owner for their credentials again.

In order to obtain a new access token, perform a POST request to the /oauth2/token token endpoint with grant_type set to refresh_token and refresh_token set to the value of the refresh token you obtained from the last call to the token endpoint. Remember that every request to the OAuth 2.0 token endpoint requires client authentication.

curl -X POST https://api.getbase.com/oauth2/token \
     -u "$CLIENT_ID:$CLIENT_SECRET" \
     -d "grant_type=refresh_token" \
     -d "refresh_token=$REFRESH_TOKEN"

Token Revocation

Base API supports OAuth 2.0 Token Revocation. You can perform a revocation request of a single access token or a single refresh token and all its related access tokens.

To revoke a token, perform a POST request to the /oauth2/revoke token revocation endpoint with token_type_hint set to either access_token or refresh_token, and token set to value of the token you want to revoke.

curl -X POST https://api.getbase.com/oauth2/revoke \
     -u "$CLIENT_ID:$CLIENT_SECRET" \
     -d "token_type_hint=refresh_token" \
     -d "token=$REFRESH_TOKEN"