Go1 uses the OAuth 2.0 standard as a framework for third parties to gain authorization and make API requests on behalf of a Go1 user.
In Go1, following OAuth 2.0 spec, OAuth clients are used to request access authorization from users, to act on their behalf, and will produce tokens that can be submitted to APIs to verify requests.
OAuth client
An OAuth client is an OAuth 2.0 entity that is used to request access on behalf of a user and by extension, it will have that user’s access and control over Go1 accounts.
The OAuth client comprises of the client ID which is a publicly exposed string used by the Go1 API to identify the OAuth client and the client secret which is used to authenticate the identity of the OAuth client and must be kept private between the third party application and the API.
Tokens
A token is an encrypted grant that gives a client limited-time permission to act as if it were the user that has authorized it. At Go1, tokens can primarily contain the following:
- A subject (usually a user’s account ID)
- Scope permissions (a list of actions that can be done with this token)
- User account details
There are other OAuth 2.0 grant types available for more specialized requests, see our API Reference for more information. When interacting with GO1’s APIs however, a user-level token is almost always the correct context.
With a token, a third party system can make requests on the user’s behalf - searching for content, creating and managing users, creating enrollments and reporting learning history. Those requests will only have the same permissions levels as the subject user, further restricted by any scopes that were applied when requesting the token.
Scopes cannot be added to non-admin users to elevate their permissions.
Abstract OAuth 2.0 Protocol Flow
1. The OAuth client makes an authorization request to access resources from the user
2. If the user authorizes the request, the OAuth client receives an authorization grant
3. The OAuth client presents authentication of its own identity along with the authorization grant requesting an access token from the authorization server (API)
4. If the OAuth client identity is authenticated and the authorization grant is valid, the authorization server (API) issues an access token to the OAuth client and authorization is complete
5. The OAuth client then requests the resource from the resource server (API) and presents the access token for authentication
6. If the access token is valid, the resource server (API) provides the resource to the OAuth client
This flow may differ depending on the authorization grant type used, but this provides a general overview. The different grant types as discussed below.
Authorization grant
In the Abstract Protocol Flow above, the first four steps provide an overview of obtaining an authorization grant and access token. The authorization grant type will differ depending on the method used by the OAuth client when requesting authorization. OAuth 2.0 defines the following grant types:
- Authorization code: used with server-side applications.
- Implicit (Token): used with mobile apps or web applications that do not have back-end applications.
- Client credentials: used by applications to obtain an access token outside of the context of a user. Typically this is used to access application resources and not to access user resources.
- Password: used to exchange user credentials for an access token.
- Refresh Token: used to exchange user credentials for an access token.
In the following, we will describe each grand type and its flow in more detail.
Grant type: Authorization code
As it was developed for server-side applications, where source code is not publicly exposed, and the client secret can be maintained confidentially, the authorization code is often the most popular grant type. The application must be able to interact with the user-agent (such as the user's browser) and receive API authorization codes that are routed through the user-agent, otherwise known as a 'redirection-based flow'.
1. Requesting authorization from a user
In Go1, the user (usually an Admin due to the level of their permissions) must authorize a third party OAuth client access to their account. To do this, create a "Log In" link sending the user to this interface.
To generate the interface use this URL, copy the below code block, editing the inputs.
https://auth.go1.com/oauth/authorize?response_type=code&client_id=<CLIENT_ID>&redirect_uri=<CALLBACK_URL>&scope=user.read user.write account.read lo.read lo.write&state=<CUSTOMERIDENTIFIER>
- https://auth.go1.com/oauth/authorize: the GO1 API authorization endpoint
- client_id=CLIENT_ID: the OAuth client ID (identifies the application to the API)
- redirect_uri=CALLBACK_URL: where to redirect the user after an authorization code is granted
- response_type=CODE: requesting an authorization code grant
- scope=SCOPES: tells the API the level of access your OAuth client is requesting. See the list of available Scope permissions
- state=STATE: to maintain the state between the request and callback e.g. when requesting a code for a particular customer
2. User authorizes OAuth client
Once the user enters their credentials, they will be asked to select which portal they wish to provide authorization for.
This authorization only grants access to the nominated portal. If access is required for multiple portals, separate authorization would be required for each of them.
3. Receive an Authorization code
After access is provided to the portal, the user will be redirected back to the third-party application (redirect_uri specified in Step 1) with an authorization code as a GET-Parameter.
User will be redirected to: PROVIDED_REDIRECT_URL/?code=AUTH_GRANT_CODE For example: https://www.go1.com/?code=AUTH_GRANT_CODE
4. Exchange an Auth token using an Authorization code
The third-party server will exchange the authorization code for an access token by making a POST request to the authorization server's token endpoint.
curl --location --request POST 'https://auth.go1.com/oauth/token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'client_id=CLIENT_ID' \ --data-urlencode 'client_secret=CLIENT_SECRET' \ --data-urlencode 'grant_type=authorization_code' \ --data-urlencode 'code=AUTH_GRANT_CODE' \ --data-urlencode 'redirect_uri=CALLBACK_URL'
The server will reply with an access token, a refresh token and the expiration time.
{
"token_type": "Bearer",
"expires_in": 43200,
"access_token": "OAUTH_TOKEN",
"refresh_token": "OAUTH_REFRESH_TOKEN"
}The "access_token" will be valid for 12 hours. If it expires, it can be refreshed by the OAuth client using the "refresh_token", which is a one-time-use token and valid for 90 days. Each refresh will give you another "refresh_token", which is valid for another 90 days. In case the "access_token" and "refresh_token" are both invalid or not stored, the user will need to reauthorize starting at step 1.
Grant Type: Implicit
If the client secret is used in such a way that does not require confidentiality, such as a mobile application or applications that run in web browsers, then the implicit grant type is often used.
As with authorization code grant types, implicit grant types can also be a 'redirection-based flow', however, the access token is this time given to the user-agent to forward to the application and subsequently could be exposed to the user and other applications on the user's device.
The implicit grant type, will not authenticate the identity of the OAuth client. Instead, it is relying on the redirect URI (previously registered with the service) to fill this gap.
Refresh tokens are also not supported by this grant type.
1. Implicit Authorization Link
To generate the interface use this URL, replacing the sections in red.
The difference here is the "response_type" parameter, which is set to "token".
https://auth.go1.com/oauth/authorize?response_type=token&client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>&scope=user.read user.write account.read lo.read lo.write
2. User authorizes OAuth client
Step 2 is the same as in the "Grant type: Authorization code" Flow.
3. Receiving an Access token
After access is granted to the portal, the user will be redirected back to the third-party application (redirect_uri specified in Step 1) with an access token as a GET-Parameter.
User will be redirected to: PROVIDED_REDIRECT_URL/?token=ACCESS_TOKEN For example: https://www.go1.com/?token=ACCESS_TOKEN
Grant type: Client credentials
To provide an application with a way to access its service account, a client credentials grant type can be used. This is helpful when an application wants to update it's registered description or redirect URI via API.
At Go1 the client credentials grant type is also used to register new portals.
The application first sends it's credentials, client ID and client secret, requesting an access token from the authorization server.
An example POST might look like this
curl --location --request POST 'https://auth.go1.com/oauth/token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'client_id=CLIENT_ID' \ --data-urlencode 'client_secret=CLIENT_SECRET' \ --data-urlencode 'grant_type=client_credentials'
The server will reply with an access token and the expiration time (12 hours).
{
"token_type": "Bearer",
"expires_in": 43200,
"access_token": "OAUTH_TOKEN",
}Grant type: Password
If your application has the user's username and password, this grant type can be used to exchange user credentials for a set of access and refresh tokens without any user involvement. At Go1, we usually recommend using this flow if the portal has been created by your application and you have stored the username and password of the portal administrator you created.
An example POST might look like this
curl --location --request POST 'https://auth.go1.com/oauth/token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'client_id=CLIENT_ID' \ --data-urlencode 'client_secret=CLIENT_SECRET' \ --data-urlencode 'grant_type=password' \ --data-urlencode 'portal_name=PORTAL_NAME' \ --data-urlencode 'username=PORTAL_ADMIN_EMAIL' \ --data-urlencode 'password=PORTAL_ADMIN_PASSWORD'
The server will reply with a set of access and refresh token and the expiration time of the access token (12 hours).
{
"token_type": "Bearer",
"expires_in": 43200,
"access_token": "OAUTH_TOKEN",
"refresh_token": "OAUTH_REFRESH_TOKEN"
}Grant type: Refresh Token
If a refresh token was included in the original response, it can be used to request a new access token from the authorization server.
Refresh tokens are one-time use only. You will get a new refresh token when exchanging it to a new access token.
An example POST request, using a refresh token to obtain a new access token, could look like this
curl --location --request POST 'https://auth.go1.com/oauth/token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=refresh_token' \ --data-urlencode 'client_id=CLIENT_ID' \ --data-urlencode 'client_secret=CLIENT_SECRET' \ --data-urlencode 'refresh_token=ACCESS_TOKEN'
The server will reply with a new set of access and refresh tokens and the expiration time of the access token (12 hours).
{
"token_type": "Bearer",
"expires_in": 43200,
"access_token": "OAUTH_TOKEN",
"refresh_token": "OAUTH_REFRESH_TOKEN"
}Access Token Usage
Once an access token has been provided, an application can use it to access the user's account. This access is limited to the scope provided and will only be available until the token expires or is removed.
An example of an API request, using curl might look like this. Note that the access token is included
curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" "https://api.go1.com/v2/ENDPOINT"
Provided the access token remains valid, the request will be processed according to API specifications. If the access token expires or is removed, an 'Invalid token' error will be presented.
API documentation