Refresh Token Flow
The refresh token flow can be used by desktop or mobile apps, server-side web apps and service accounts. The client should be able to store the refresh token to access Space resources even when the end-user is not online.
The client should be registered with Space as Server-side Web App, Mobile or Desktop App or Service Account.
Prior to making a refresh request, the client application should have obtained a
refresh_token from Space. Space supports issuing refresh tokens for the Authorization Code Flow and Resource Owner Password Credentials Flow authorization flows.
Refreshing an access token
The client 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 client|
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.
AddNewProfile,AddNewTeam Team:EditTeam Profile:EditAbsences,EditLanguages Project:*
The rights you specify in
Because refresh tokens are typically long-lasting credentials used to request additional access tokens, the refresh token is bound to the client to which it was issued. If the client type is confidential or the client was issued client credentials (or assigned other authentication requirements), the client must authenticate with the Space server as described in RFC 6749.
The client makes the HTTP request in the following format using transport-layer security:
Example (with extra line breaks for display purposes only):
Require client authentication for confidential clients or for any client that was issued client credentials (or with other authentication requirements)
Authenticate the client if client authentication is included and ensure that the refresh token was issued to the authenticated client.
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 client 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 client. If a new refresh token is issued, the refresh token scope must be identical to that of the refresh token included by the client 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 client, or is otherwise malformed.
invalid_client— Client authentication failed (e.g., unknown client, no client 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 client 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 client.
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 client.
unauthorized_client— The authenticated client 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 client developer in understanding the error that occurred.
- A URI identifying a human-readable web page with information about the error, used to provide the client 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.