oauth API methods
Generate and manage OAuth tokens.
Authorize a user
GET /oauth/authorize HTTP/1.1
Displays an authorization form to the user. If approved, it will create and return an authorization code, then redirect to the desired redirect_uri
, or show the authorization code if urn:ietf:wg:oauth:2.0:oob
was requested. The authorization code can be used while requesting a token to obtain access to user-level methods.
Returns: String (URL) or HTML response
OAuth: Public
Version history:
0.1.0 - added
2.6.0 - added force_login
3.5.0 - added lang
Request
Query parameters
- response_type
- required String. Should be set equal to
code
. - client_id
- required String. The client ID, obtained during app registration.
- redirect_uri
- required String. Set a URI to redirect the user to. If this parameter is set to
urn:ietf:wg:oauth:2.0:oob
then the authorization code will be shown instead. Must match one of theredirect_uris
declared during app registration. - scope
- String. List of requested OAuth scopes, separated by spaces (or by pluses, if using query parameters). Must be a subset of
scopes
declared during app registration. If not provided, defaults toread
. - force_login
- Boolean. Forces the user to re-login, which is necessary for authorizing with multiple accounts from the same instance.
- lang
- String. The ISO 639-1 two-letter language code to use while rendering the authorization form.
Response
200: OK
The authorization code will be returned as a query parameter named code
.
redirect_uri?code=qDFUEaYrRK5c-HNmTCJbAzazwLRInJ7VHFat0wcMgCU
400: Client error
If the authorization code is incorrect or has been used already, the request will fail.
{
"error": "invalid_grant",
"error_description": "The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client."
}
Obtain a token
POST /oauth/token HTTP/1.1
Obtain an access token, to be used during API calls that are not public.
Returns: Token
OAuth: Public
Version history:
0.1.0 - added
Request
Form data parameters
- grant_type
- required String. Set equal to
authorization_code
ifcode
is provided in order to gain user-level access. Otherwise, set equal toclient_credentials
to obtain app-level access only. - code
- String. A user authorization code, obtained via GET /oauth/authorize.
- client_id
- required String. The client ID, obtained during app registration.
- client_secret
- required String. The client secret, obtained during app registration.
- redirect_uri
- required String. Set a URI to redirect the user to. If this parameter is set to urn:ietf:wg:oauth:2.0:oob then the token will be shown instead. Must match one of the
redirect_uris
declared during app registration. - scope
- String. List of requested OAuth scopes, separated by spaces (or by pluses, if using query parameters). If
code
was provided, then this must be equal to thescope
requested from the user. Otherwise, it must be a subset ofscopes
declared during app registration. If not provided, defaults toread
.
Response
200: OK
Store this access_token for later use with auth-required methods. The token should be passed as an HTTP Authorization
header when making API calls, with the value Bearer access_token
{
"access_token": "ZA-Yj3aBD8U8Cm7lKUp-lm9O9BmDgdhHzDeqsY8tlL0",
"token_type": "Bearer",
"scope": "read write follow push",
"created_at": 1573979017
}
400: Client error
If you try to request a scope that was not included when registering the app, the request will fail.
{
"error": "invalid_scope",
"error_description": "The requested scope is invalid, unknown, or malformed."
}
401: Unauthorized
If client_id and client_secret do not match or are invalid, the request will fail.
{
"error": "invalid_client",
"error_description": "Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method."
}
Revoke a token
POST /oauth/revoke HTTP/1.1
Revoke an access token to make it no longer valid for use.
Returns: empty object
OAuth: Public
Version history:
x.x.x - added
Request
Form data parameters
- client_id
- required String. The client ID, obtained during app registration.
- client_secret
- required String. The client secret, obtained during app registration.
- token
- required String. The previously obtained token, to be invalidated.
Response
200: OK
If you own the provided token, the API call will provide an empty response. This operation is idempotent, so calling this API multiple times will still return OK.
{}
403: Forbidden
If you provide a token you do not own, or no token at all, the API call will return a 403 error.
{
"error": "unauthorized_client",
"error_description": "You are not authorized to revoke this token"
}
See also
POST /api/v1/apps app/controllers/oauth/authorizations_controller.rb app/controllers/oauth/authorized_applications_controller.rb app/controllers/oauth/tokens_controller.rbLast updated February 6, 2023 路 Improve this page