xREL.v3

OAuth Basics
OAuth is an industry standard for authentication. Please read Wikipedia for details. There are many client implementations available, and you likely don't have to write your own.

OAuth on xREL
xREL currently implements OAuth 2.0. Two grant types are supported: Authorization Code Grant and Client Credentials Grant. In brief, Authorization Code Grant is used to authenticate users, while the Client Credentials Grant is used to authenticate the application itself, in cases when no user context is needed (i.e. you need to access a protected method).

Authorization Code Grant
This grant is like the grant used in OAuth 1. It starts by redirecting your users to oauth2/auth, with a few HTTP GET parameters set. The most important parameter is the redirect_uri:

• If you are writing a web based application, you set this to a script on your website. After the user authenticates your app on xREL, he will be directed to this script. It will have a HTTP GET parameter ?code=XXX. You need this code for the second step (see below).
• If you are writing a mobile or desktop application, you may set this to urn:ietf:wg:oauth:2.0:oob or urn:ietf:wg:oauth:2.0:oob:auto. With the former, the user will see a code after authentication, with a prompt stating that he should enter/copy it into the app. If your application has access to the web browser, you may use the latter. The user will then only see a prompt to close the window, and you may parse the code from the <title> HTML tag.

With this code, you may request an access token at oauth2/token. Please see below for details on the access code.

Client Credentials Grant
This grant is used to authenticate your application, without an active user context. This grant only has advantages if you need to call protected methods. If you don't have access to any protected methods, you don't need to use it, as it has no other advantages.
It is a lot simpler than the Authorization Code Grant. It only uses oauth2/token, omitting the code.

Access Tokens
A response from oauth2/token may look like this:


Point by point it means the following:

• access_token: The access token, with which you may do requests to protected resources. It is a JSON Web Token, which you can verify and decode for more information (e.g. scopes & lifetime).
• token_type: This value is always Bearer.
• expires_in: Lifetime of the access token.
• refresh_token: With the refresh token you may request a new access_token after it has expired. Its lifetime is unlimited, however you can only use it once. You will get a new refresh_token when renewing the access_token.

Authenticating using an access token
Just send an extra HTTP header with every request: Authorization: Bearer XXX, with XXX being the access token. Note that xREL does NOT support simply passing the access_token as a HTTP GET parameter.

Renewing an access token
Access token expire after one hour. If you need to make a request afterwards, you need to renew the access token. You do this by simply sending a refresh_token request to oauth2/token. You don't have to do the oauth2/auth step again. Note that the refresh_token can only be used once, you'll get a new refresh_token every time you refresh the access token.

Notes

• You can have a maximum of 3 sessions per app and user.
• If you use the Client Credentials Grant, rate limiting counts against the IP.
• You may use the state parameter for extra security during oauth2/auth, especially when your application is a website.
• A very good and detailed description is also available on Google Developers. xREL behaves mostly as described in that document.
• For details on error handling, please see here.