The Anchor API (v2+) requires authentication via OAuth2. It supports authorization code, refresh token, and password grants.
This document will not go into the details of the OAuth2 specification, but instead will focus on simple steps for using it with Anchor. Anchor's implementation of OAuth2 is based on RFC 6749.
https://<hostname:port>/oauth
All requests to the OAuth2 API must be performed over HTTPS. Non-HTTPS requests will be rejected.
Started by registering a new application for your organization, or by asking your organization administrator to complete the registration. Visit the "API" page in organization settings and click "Register OAuth2 Client".
Provide the following details for your application:
Upon completion a unique, random client ID and client secret will be generated. These typically need to be configured within the registered application before it can authenticate.
The following steps outline how your application interacts with the server to obtain a user's consent and get access tokens.
https://<hostname:port>/oauth/authorize?
response_type=code&
client_id=your_client_id&
redirect_uri=https%3A%2F%2Fyour-application.com/oauth2/callback&
state=state_value
The user will be presented with an authorization page requesting them to allow your application to access their account. Your application does not do anything but wait for the server to redirect back after the user approves or denies the request.
After the user completes the consent step, the server redirects to the provided redirect_uri with a code or error query parameter, as well as state if provided.
https://your-application.com/oauth2/callback?code=XXXXXXXXXXXXXXXX
https://your-application.com/oauth2/callback?error=access_denied
Your application can then exchange the authorization code for access tokens using the token endpoint below.
To request an access token, call the token method, passing an authorization code or account credentials
to authenticate.
POST /oauth/token
POST /oauth/token grant_type=password&client_id=anchor&username=user@example.com&password=example
HTTP status code: 200
Response body:
{
"access_token": "<access_token>",
"expires_in": 3600,
"guid": "<guid>",
"token_type": "Bearer",
"refresh_token": "<refresh_token>",
"scope": "full"
}
The response should be saved. The access token will be passed to API methods requiring authentication. Access tokens are valid for a
short period of time, usually 1 hour, and the refresh token will be used to get a new access token when it expires. The expires_in
value is in seconds. token_type and scope will always be "Bearer" and "full," respectively.
The guid returned in the response is either the GUID passed in the original request, if it is found on the server, or a
new GUID assigned to the client. It should be saved for future use when refreshing tokens.
When an account has two-step verification enabled, the initial call will return the following:
HTTP status code: 401
Response body:
{
"error": "missing_totp",
"two_step_mode": "(email|sms|authenticator)"
}
In this case, the user should be prompted for a two-step verification code and the request should be repeated with the code appended. The Anchor server will have already triggered the notification process in the case of email or SMS delivery.
POST /oauth/token grant_type=password&client_id=anchor&username=user@example.com&password=example&auth_code=<auth_code>
If the code is valid, an access token will be returned. Otherwise, the following:
HTTP status code: 401
Response body:
{
"error": "invalid_totp",
"two_step_mode": "(email|sms|authenticator)"
}
If repeated failed authentication attempts occur, the account will be blocked from making more authentication attempts for a short period:
HTTP status code: 403
Response body:
{
"error": "account_locked"
}
Refreshing an access token also uses the same token method as the initial authentication request. In this case, the
refresh_token from a previous access token request is passed instead of account credentials.
POST /oauth/token
POST /oauth/token grant_type=refresh_token&client_id=anchor&refresh_token=<refresh_token>
HTTP status code: 200
Response body:
{
"access_token": "<access_token>",
"expires_in": 3600,
"guid": "<guid>",
"token_type": "Bearer",
"refresh_token": "<refresh_token>",
"scope": "full"
}
To invalidate an access token, call the revoke method.
POST /oauth/revoke
POST /oauth/revoke client_id=anchor&token=<token>&token_type_hint=access_token
HTTP status code: 200
For valid requests the response is always HTTP 200. The response body is ignored.
Once an access token is obtained, it may be used to authenticate requests by passing it in the Authorization header.
GET /api/2/files/1 Authorization: Bearer <access_token> ...