Refresh Token Flow
The refresh token flow is best suited for desktop apps, mobile apps, and server-side web apps. The application should be able to store a refresh token to access Space resources even when the end-user is not online.
After the application obtains an access token using Authorization Code Flow or Resource Owner Password Credentials Flow, it can make refresh requests to Space. These requests let the application automatically obtain a new access token once the lifetime of the current one expires.
You don't have to explicitly enable the flow for an application during the registration– the flow is enabled automatically once you enable Authorization Code Flow or Resource Owner Password Credentials Flow.
If you use Space SDK in your application, you can implement the flow with the help of the
For more details on the flow, refer to Refresh token for Authorization code flow specification.
Refreshing an access token
The application makes a refresh request to the token endpoint
<Space service URL>/oauth/token by adding the following parameters to the HTTP request entity-body in the
application/x-www-form-urlencoded format with UTF-8 character encoding:
- Specifies the grant type in an OAuth 2.0 request. Required. Set value to
- Required. The refresh token issued to the application.
Required. A space separated list of rights required to access specific resources in Space.
The rights are grouped in four categories: Global, Profile, Team, Project. Use the following syntax to specify the rights (shown here in BNF notation):<SCOPE> ::= <ALL> | <TOKEN_LIST> <ALL> ::= '**' <TOKEN_LIST> ::= <TOKEN> (' ' <TOKEN>)* <TOKEN> ::= <GLOBAL_PERMISSIONS_TOKEN> | <ENTITY_PERMISSIONS_TOKEN> <GLOBAL_PERMISSIONS_TOKEN> ::= <PERMISSIONS> <ENTITY_PERMISSIONS_TOKEN> ::= <ENTITY> ':' <PERMISSIONS> <ENTITY> ::= 'Team' | 'Project' | 'Profile' | 'etc.' <PERMISSIONS> ::= <ALL_PERMISSIONS> | <PERMISSION_LIST> <ALL_PERMISSIONS> ::= '*' <PERMISSION_LIST> ::= <PERMISSION> (',' <PERMISSION>)*
Wildcards are accepted. For global rights, category is omitted.
Example:AddNewProfile,AddNewTeam Team:EditTeam Profile:EditAbsences,EditLanguages Project:*
The rights you specify in
scopeshould be first added to the list of requested rights and authorized for your application in Space.
Because refresh tokens are typically long-lasting credentials used to request additional access tokens, the refresh token is bound to the application to which it was issued. If the application type is confidential or the application was issued application credentials (or assigned other authentication requirements), the application must authenticate with the Space server as described in RFC 6749.
The application makes the HTTP request in the following format using transport-layer security:
Example (with extra line breaks for display purposes only):
Require application authentication for confidential applications or for any application that was issued application credentials (or with other authentication requirements)
Authenticate the application if application authentication is included and ensure that the refresh token was issued to the authenticated application.
Validate the refresh token.
If the refresh token is valid and authorized, Space issues an access token.
Along with new access token, Space may issue a new refresh token, in which case the application must discard the old refresh token and replace it with the new one. Space may revoke the old refresh token after issuing a new refresh token to the application. If a new refresh token is issued, the refresh token scope must be identical to that of the refresh token included by the application in the request.
If the request has failed verification or is invalid, Space returns an error response.
A single ASCII [USASCII] error code from the following:
invalid_request— The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the application, or is otherwise malformed.
invalid_client— Application authentication failed (e.g., unknown application, no application authentication included, or unsupported authentication method). Space may return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported. If the application attempted to authenticate via the "Authorization" request header field, the Space server will respond with an HTTP 401 (Unauthorized) status code and include the "WWW-Authenticate" response header field matching the authentication scheme used by the application.
invalid_grant— The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another application.
unauthorized_client— The authenticated application is not authorized to use this authorization grant type.
unsupported_grant_type— The authorization grant type is not supported by Space.
invalid_scope— The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.
- Human-readable ASCII [USASCII] text providing additional information, used to assist the application developer in understanding the error that occurred.
- A URI identifying a human-readable web page with information about the error, used to provide the application developer with additional information about the error.
The parameters are included in the entity-body of the HTTP response using the "application/json" media type. The parameters are serialized into a JSON structure by adding each parameter at the highest structure level. Parameter names and string values are included as JSON strings. Numerical values are included as JSON numbers. The order of parameters does not matter and can vary.