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 Sell 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 POST 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 Sell 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 tocode.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, Sell 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, Sell 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 Sell 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 totoken.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, Sell 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, Sell 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 Sell supports. The flow is optimized for cases where you may want to authenticate directly via Sell 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 Sell 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.
The old refresh_token will be valid until the new access_token is used for the first time.
This allows API clients to handle faults causing new refresh_token and new access_token to be lost after they were generated, but before they were used for the first time.
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
Sell 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"