This document is an interactive guide to using the authentication system for API access. You can follow through this document and input your own credentials to try using authentication for real.
For background on Authentication and OAuth 2.0, please see the Authentication overview
We will be attempting to access a demo scope called
You may want to logout first to get the full experience, or jump straight to the login / grant scope step.
- Logout - start fresh
- Login / grant scope - login and grant a 3rd party access to your details
- Get an access token - confirm the access with the authentication server
- Use the access token - use the access
- Refresh the access token - extend the access when is about to expire
This tutorial uses our test environment. A demo client ID, secret and user account are provided below. See test environments for more details of this environment.
If you have already requested API access and received your test client ID, secret and user accounts, you can
use these instead. You will need to enter the redirect URI you supplied in your application, and change the
Once you have completed testing and received your live API credentials, you can also try out the live environment with this page.
Before you start with authentication, you may want to ensure your user is logged out. Don't worry if the page that loads is blank, the important point is that you are presented with a login screen at the next step.
Login / grant scope
After this your user will need to login to grant access to the scope. If the user is already logged in, they will just be presented with the prompt to access the scope. The scope you need will depend on the application you are trying to access.
If the login is successful, the redirect URL will be followed.
This would typically be back to your app. Notice the
?code=... query string added to the end of the returned URI.
This is the token you will need to exchange with the authentication server in the next step.
state parameter is used to maintain state between the request and callback. This should be used for preventing
cross-site request forgery as described in OAuth 2.0 specification (particulary
sections 4.1.1 and 10.12).
Get an access token
The step above should have presented you with a successful redirect from the authentication server to your Redirect URI. But how do know that the redirect came from the authentication server and not a malicious user?
Your application will now need to check with the authentication server to prevent people from spoofing your Redirect URI by confirming the code. This will give you an access token, which you will use to access all further API resources.
codefrom the previous step here to continue.
[[ tokenResponse ]]
[[ tokenError.responseText ]]
Use the access token
You now have an access token you can use to access an API.
Refresh the access token
At any time before the access token expires, you can refresh it, to get a new access and refresh token. This can happen in the background, without requiring input from your users.
You can perform this action as many times as you like, as long as the existing access token has not yet expired.
[[ tokenRefreshResponse ]]
[[ tokenRefreshError.responseText ]]