⭑ Note: Unlike the out of the box security code solution, access and ID tokens require setting up a process on AODocs to whitelist client IDs. This is not currently possible out of the box.
In general, a Bearer token is a piece of data that acts as a permit to operate on resources, passed in the Authorization header of requests.
Two main types of Bearer tokens exist:
A user who has access to resources on a resource server tells the authorization server it’s OK for the client app to have the same access. The client app then gets a permit (token) it can present to the resource server with each request.
The main reason to use access or ID tokens (instead of security code) is to provide the client app with secure delegated access to server resources on your behalf. It allows authorizing a client app to access and manipulate server resources within a specific scope/time, and without exposing the user’s credentials to the app.
When a client app gets the user to authenticate, Google can generate two types of tokens:
Both types of tokens can be generated in a single authentication request, but only one of them is usually necessary. After this step, the AODocs authentication flow is similar, but with some key differences.
Each request to AODocs APIs must satisfy two requirements: identify the user, and certify that the provided token was generated by Google. Either of the tokens issued by Google is capable of providing this proof, so the client app can choose which token serves its purposes better.
💡 Tip: The ID token is sufficient to perform AODocs-only actions. Meanwhile, the access token has the same capability, but additionally allows AODocs to impersonate the user to get access to the Drive scopes required to call Drive APIs.
There are many ways of obtaining an OAuth 2.0 token. Describing all the use cases is beyond the scope of this article. You can read more about Google’s approach on the following Google documentation pages:
When you receive tokens from Google, they should look something along the lines of the following.
{
"access_token": "ya29.Il-3B5J8...Fhl3a-yRjpg",
"id_token": "eyJhbGc8i...AaNVQ"
"expires_in": 3600,
"token_type": "Bearer",
"scope": "openid https://www.googleapis.com/auth/userinfo.email",
"refresh_token": "1//04c68...AGAQSNwF-L9Ir2s...M9yc8AqB-u04JncA...68nWovE"
}
⭑ Note: Access tokens usually start with the string
ya29., and because they’re opaque (not actual data but pointers to data elsewhere), they’re usually shorter than ID tokens. The latter are longer because they contain actual data, encoded into three pieces: header, claims, and signature.
Once you have obtained a token, you select which token is more appropriate for your use case:
You can access AODocs APIs by including one of the tokens as an Authorization HTTP header’s Bearer value:
Authorization: Bearer < access_token | id_token >
GET https://aodocs.altirnao.com/api/document/v1 HTTP/1.1
Authorization: Bearer [YOUR_TOKEN] \
Accept: application/json \
Content-Type: application/json \
{
"libraryId": "Rngc1ug8K6WmL3IjZ8"
}
All Bearer tokens have a built-in expiration. If you requested offline access to token scopes, you can refresh tokens as necessary without having to prompt the user for permission.
Token errors occur only when the token is:
All of these result in status code 401: Unauthorized as listed in HTTP status codes and error scenarios.
To create, manage, and troubleshoot your tokens, see the Google Developers OAuth 2.0 Playground .