The User Authentication Flow

User authentication (or "authorization code flow" as it called in the OAuth 2.0 specification) is the process that grants applications the ability to perform actions on behalf of a user. Your application will redirect the user to our authorization servers and the user is then asked to confirm or deny authorization to your application.

It may be helpful to view our self contained PHP-based example that outlines the entire process from authentication to API call.

There are three steps:

  1. An app asks the user for authorization by redirecting them to our authorization endpoint, and receives an authorization code.
  2. If confirmed by a user, the app makes a request to our server to exchange its secret and the authorization code it just received from the user for an authorization token.
  3. The app can now make authenticated API calls by sending the access token in every request.

Flow Diagram

Step 1: Redirect the User to our Authorization Server

Redirect the user to to make an authorization request. If you are in a mobile setting, this must be sent via a native browser, not an in-app browser. Here are the parameters:

Request ParameterDescription
scope The scope(s) you need. Separate multiple scopes with spaces.
client_id Your Client ID.
response_type Always use the string "code"
state A random string generated by you. You send us this, and we'll send it back to you, and you verify that we send back the same thing you sent.
You must send and verify this value in order to prevent CSRF attacks.
redirect_uri (optional) A URI to which we should redirect the user. See "about redirect URIs" for details.

An example URL you'd redirect the user to:

User authorizes your application

If the user authorizes your application, our server will redirect the user to the provided redirect URI (or the redirect URI registered, if you didn't provide one). The code your app receives will only last for 60 seconds. An example of the response looks like:

HTTP/1.1 302 Found
Location: YOUR_URL/?code=GENERATED_CODE&state=YOUR_STATE&expires_in=60

User denies your application

If the user denies access to your application, our server will redirect the user to your URI with error="access_denied" as the query parameter. For example:

HTTP/1.1 302 Found
Location: YOUR_URL/?error=access_denied&error_description=The+user+denied+access+to+your+application

Any other error that occurs will be similarly displayed in the query parameter as above.

Step 2: Request a token from our authorization server

Using the authorization code you received from the previous step you can now request an access token from our authorization server. Send your request using POST to and specify:

Required ParameterDescription
grant_type You must set this to the string "authorization_code".
code The authorization code you received after the user successfully authenticated.
redirect_uri Either your registered URI or the one you sent us in the first step (this is used to help validate your request).
Note: Unlike step one, this is mandatory for this step.
Basic Authorization Using HTTP Basic Authorization you need to specify your client ID and secret (see the API dashboard). This is simply your client ID and password separated by a colon (:) and base64-encoded. For example, if your client ID is "123" and your secret is "a1s2", you would base64 encode the string "123:a1s2" which is "MTIzOmExczI=".

An example HTTP request would look like:

POST /oauth/token HTTP/1.1
Authorization: Basic MTIzOmExczI=
Content-Type: application/x-www-form-urlencoded; charset=UTF-8


Valid Access Token

If the code is valid, our authorization server will send a 200 OK response with an access token. For example:

	"access_token": "46a54395f3d1108feca56c7f6ca8dd3d",
	"token_type": "bearer",
	"expires_in": 3600,
	"scope": "read",
	"user_id": "USERNAME"

Notice that in addition to the access token, we tell you when it will expire (in this example, it's 3,600 seconds, or 1 hour), the scope your token is valid for (this will match what you requested from the user in step 1) and tell you the username of the user who authorized your application.

Error Response

If there is a problem with your request, our authorization server will instead send a 400 Bad Request with an error message. An example error:

	"error": "invalid_request",
	"error_description": "Invalid grant_type parameter or parameter missing",

Step 3: Make an API call

Now that you have an access token you can make API calls on behalf of the user who authorized your application by sending the access token along with your request. See Making API Calls for details.

Self contained example

See our PHP example for a complete example of how to make calls.

About Redirect URIs

The "redirect URI" is where our server will redirect users to after they approve (or deny) your application at the authorize endpoint:

In addition to registering a redirect URI when you sign up as a developer for API 2.0, your application must also pass a redirect URI as part of the request. The redirect URI you send with the request must start with the same characters as the one you registered with us. In other words, it can only be more specific.

For example, assuming your registered redirect URI is, and if the one you send as a request parameter is:

  • then it's OK
  • then it's OK
  • then it will FAIL (because the redirect URI directory is higher than the registered one)
  • then will FAIL (because the domain is different from the registered one)
  • then it will FAIL (because the scheme is different)

Mobile Application Redirect URIs

When using mobile applications, your redirect URI should be a custom url scheme registered with the operating system.

For example, if your native application were called "Flashcards Foo", your redirect URI might be:
flashcards-foo:/after_oauth. Using iOS? Check out this tutorial.

Create Set