Watch Shop
Submit
INFO
APIS
TOOLS

Gaining OAuth 2.0 Credentials

In order to make API calls, you must first register your application (after logging in with your DeviantArt account)

After you've registered, you'll gain access to a pair of client_id and client_secret codes on the Applications & Keys page.

You can read the OAuth2 specification at http://tools.ietf.org/html/rfc6749 and the Bearer Token specification at http://tools.ietf.org/html/rfc6750

OAuth2 Basics

The API supports three of OAuth2's grant types, Authorization Code, Implicit, and Client Credentials. Authorization Code and Client Credentials are used to access private and public endpoints respectively, they have very different authentication flows and are treated as separate authentication methods. Endpoints will document their required authentication method in the Authentication section of the endpoint documentation. Implicit is used for clients that are public and cannot protect their client_secrect such as Javascript or Mobile clients.

Authorization Code

The Authorization Code grant is the most common OAuth2 grant type and gives your app access to aspects of a users account. An overview of the authentication flow is illustrated below:

Client Credentials

The Client Credentials gives your app access to our "public" endpoints and do not require user authorization. An overview of the authentication flow is illustrated below:

Implicit

The Implicit grant is the same as Authorization Code but does not include a refresh token and the token is returned in the fragment of the redirect_uri. An overview of the authentication flow is illustrated below:

Using The Authorization Code Grant

User Authorization

Before making API calls for a user, you must ask that user to authorize your application. First you should redirect the user to DeviantArt's authorization URL along with the required query-string parameters below.

https://www.deviantart.com/oauth2/authorize
Parameters Successful Response

A successful response means that the user will be redirected to your whitelisted URI along with the following GET parameters:

GET code (string) :
The code will be returned to you on successful authorization, you can then use this to obtain the access_token
GET state (string) :
optional
If you included the state parameter in your initial redirect request, that value will be returned to you in this field.
Unsuccessful Response

If the authorization request fails for any reason, the user will be redirected back to your whitelisted URI along with the following GET parameters:

GET error (string) :
The error code for the error as defined by the specification see http://tools.ietf.org/html/rfc6749#section-4.1.2.1
GET error_description (string) :
The description of the error.

Please read the error documentation for detailed error handling guidelines.

Example Authorization Redirect
GET https://www.deviantart.com/oauth2/authorize?response_type=code&client_id=0&redirect_uri=http://myapp.example/cb&scope=basic&state=mysessionid

Getting A User Access Token

Once you have the code from the authorization step, you can then request an access_token to gain access to the API resources. You do this by sending a request to the /token endpoint.

https://www.deviantart.com/oauth2/token
Parameters
POST, GET client_id (integer) :
required
Your app's client_id (obtained during app registration)
client_id and client_secrect can be provided via HTTP Basic Authentication see http://tools.ietf.org/html/rfc6750#section-2.1
POST, GET client_secret (string) :
required
Your app's client_secret (obtained during app registration)
client_id and client_secrect can be provided via HTTP Basic Authentication see http://tools.ietf.org/html/rfc6750#section-2.1
POST, GET grant_type (string) :
required
The value must be authorization_code unless you are refreshing a token (see Refreshing An Access Token)
POST, GET code (string) :
required
The code from the authorization step.
POST, GET redirect_uri (string) :
required
The redirect_uri sent with the authorization request to obtain the code, this must exactly match the value sent in that request.
This is only required if grant_type is set to authorization_code
This is currently only enforced for clients created after Feb 14th 2014, it will be enforced for ALL clients on July 23rd 2014.
Successful Example Unsuccessful Example

Refreshing An Access Token

All access_token's expire after one hour, after expiration you either need to re-authorize the app or refresh your access token using the refresh_token from the /token request.

The refresh_token will expire after 3 months, after that time you must re-authorize the app.

Parameters
POST, GET client_id (integer) :
required
Your app's client_id (obtained during app registration)
client_id and client_secrect can be provided via HTTP Basic Authentication see http://tools.ietf.org/html/rfc6750#section-2.1
POST, GET client_secret (string) :
required
Your app's client_secret (obtained during app registration)
client_id and client_secrect can be provided via HTTP Basic Authentication see http://tools.ietf.org/html/rfc6750#section-2.1
POST, GET grant_type (string) :
required
The value must be refresh_token
POST, GET refresh_token (string) :
required
The refresh_token of the Bearer token.
Example Token Refresh

Using The Client Credentials Grant

Getting A Client Access Token

To obtain a client access token, you simply request a token using your clients client_id and client_secret.

Parameters
POST, GET client_id (integer) :
required
Your app's client_id (obtained during app registration)
client_id and client_secrect can be provided via HTTP Basic Authentication see http://tools.ietf.org/html/rfc6750#section-2.1
POST, GET client_secret (string) :
required
Your app's client_secret (obtained during app registration)
client_id and client_secrect can be provided via HTTP Basic Authentication see http://tools.ietf.org/html/rfc6750#section-2.1
POST, GET grant_type (string) :
required
The value must be client_credentials
Successful Example Unsuccessful Example

Using The Implicit Grant

Getting Authorization And Access Token

To obtain an access_token using the implicit grant you redirect the user to the authorization url and the access_token will be returned to your client in the fragment of the redirect_uri you provided.

Note that to use the implicit grant you must configure your clients grant_type in the clients settings. Implicit clients also require https redirect_uri's and whitelisted uris must exactly match.

https://www.deviantart.com/oauth2/authorize
Parameters Successful Example Unsuccessful Example

Placebo Call

The first and most basic authenticated API call. It checks that a given access_token is still valid. The endpoints are:

https://www.deviantart.com/api/v1/oauth2/placebo
Example Notes

This call is most useful for checking that an access_token is still valid before making another API call that might take a long time (like a file upload). This way, if a token has expired, your users won't have to wait until the upload (or any other long-running API call) returns an error before your app notices and makes a /token call to refresh the expired token.

Revoking Access / Logging Out

Sometimes the user may want to logout or revoke access to the application, in these situations the application may choose to revoke access by itself. Note that if the application provides a means to logout, you should implement this call.

To manually revoke access you can provide either an access_token or refresh_token to identify the user and revoke your applications access to their account. This will revoke all access tokens, refresh tokens and authorizations, meaning applications would need to restart the authorization process to obtain account access again.

The default revoke removes all tokens for the user, if you want to just revoke a single device/session you can pass revoke_refresh_only=true. This will just revoke the refresh_token that is sent in with the revoke request.

POST https://www.deviantart.com/oauth2/revoke
Example