Authentication (OAuth 2.0)
Table of contents
- Introduction
- Which OAuth 2.0 grant to implement
- Requesting an access token for server side calls without user permission (Client Credentials Grant)
- Requesting an access token for user access (Authorization Code Grant)
- Refreshing an expired access token (Refresh Token Grant)
- Accessing the APIs using an access token
Introduction
RouteYou uses OAuth 2.0 for authentication to our APIs. With OAuth an external application can request access (authorization) to a user's data while keeping the user's authentication details safe. You can find more information on how OAuth works here.
Before you can start developing, it is necessary to register your application. To register your application, you need to pass the following information to your RouteYou contact person. If you don't have a contact person yet, please contact sales[at-r.].
- Name of your application
- Short description (maximum 255 characters)
- Logo: this will be shown to the user
- Redirect URI(s): one or more URIs on your website to redirect to after the user has logged in on RouteYou. Don't forget to include the redirect URI(s) for your development and testing environments.
- Scopes you will need
- account:basic: access to public account information such as name, avatar, …
- account:detail: scope account:basic + access to private account information such as shared position, email address, …
- content:read: access to all public content of a user
- content:read_all: scope content:read + access to private content of a user
- content:write: access to edit a user's content that is visible to the app
- Is your application a server app, browser based app or native app?
When the application only does server side calls, we mark the client as confidential. We expect the client secret to be passed when requesting a token.
When it is impossible to safely use the client secret (browser based or native app), the client is marked as not confidential. The client secret is not required, but the PKCE parameters should be used.
When your application is registered, a client ID and client secret will be assigned. The secret is used for authentication and should never be shared. The secret should never be used when the client can't keep it safe (browser based/native app).
Which OAuth 2.0 grant to implement
For more information see https://oauth2.thephpleague.com/authorization-server/which-grant/
- Client Credentials Grant: for server side calls that don't need user permissions
- Authorization Code Grant: for server side calls with user permissions
- Authorization Code Grant with PKCE:
- for browser based/native apps that need user permissions, instead of using the client secret (client secret can not be kept safe)
- for server side calls with user permissions, in combination with a client secret to prevent authorization code injection attacks
Requesting an access token for server side calls without user permission (Client Credentials Grant)
Perform a POST request to https://api.routeyou.com/2.0/rest/oauth/token
Request parameters:
- grant_type: "client_credentials"
- client_id: The ID of your application. This is obtained during registration of the application.
- client_secret: The client secret obtained during registration. Only use this when you can keep the client secret safe.
Response: JSON containing the following values
- token_type: "Bearer"
- expires_in: Time before the access token expires in seconds.
- access_token: The token you will use to make API calls (see below).
Example:
curl -X POST https://api.routeyou.com/2.0/rest/oauth/token \ -d grant_type=client_credentials \ -d client_id=<client ID> \ -d client_secret=<client secret>
Requesting an access token for user access (Authorization Code Grant)
Step 1
Redirect the user to https://www.routeyou.com/oauth/authorize (login flow) or https://www.routeyou.com/oauth/authorize/register (registration flow)
URL parameters:
- response_type: "code"
- client_id: The ID of your application. This is obtained during registration of the application.
- redirect_uri: The URL to which the user will be redirected after authentication. This must match one of the redirect URIs you provided when registering your application.
- scope: Scopes separated by a space (URL-encoded as +). Request only the scopes you require.
- state: A random string which will be returned in the redirect URI for additional security.
- code_challenge (optional): See PKCE below.
- code_challenge_method (optional): See PKCE below.
- email (optional): Prefill the user's email adress.
- name (optional): Prefill the user name (registration flow only).
- language (optional): Determines the language the login/register screen is shown. Prefill the user's language in the registration flow only.
- country (optional): Prefill the user's country using the country iso2 value (registration flow only).
Example URL:
https://www.routeyou.com/oauth/authorize?response_type=code&client_id=<client ID>&redirect_uri=<redirect URI>&scope=account:basic+content:read&state=abc123
Response:
RouteYou will redirect the user agent to the redirect_uri that is provided, with added URL parameters. When access is denied, error=access_denied will be included in the query string. When access is accepted, the code and state will be returned in the query string. You must match the returned state parameter to the state parameter you provided for security. The code parameter contains the authorization code needed to complete the authentication process in step 2.
PKCE (Proof Key for Code Exchange)
The code_challenge and code_challenge_method are required when it is not possible to keep your client secret safe.
- Code verifier: This is a cryptographically random string using the characters A-Z, a-z, 0-9, and the punctuation characters -._~ (hyphen, period, underscore, and tilde), between 43 and 128 characters long.
- Code challenge: Base64-URL-encoded string of the SHA256 hash of the code verifier when code challenge method is S256. Plain code verifier string when the clients don't have the ability to perform a SHA256 hash.
- Code challenge method: S256 or plain.
Step 2
Perform a POST request to https://api.routeyou.com/2.0/rest/oauth/token to exchange the authorization code from step 1 for an access token and a refresh token.
Request parameters:
- grant_type: "authorization_code"
- client_id: The ID of your application. This is obtained during registration of the application.
- client_secret: The client secret obtained during registration. Don't pass the client secret when you can't keep it confidential (browser/native app), in that case use the PKCE values.
- code: The authorization code received from the authorization server in step 1.
- redirect_uri (optional): When passed, this has to be exactly the same URI as in the initial request.
- code_verifier (optional): The code verifier from the previous step. This is required when the code_challenge was passed in the previous step. See PKCE.
Response: JSON containing the following values
- token_type: "Bearer"
- expires_in: Time before the access token expires in seconds.
- access_token: The token you will use to make API calls (see below).
- refresh_token: A new refresh token.
Example:
curl -X POST https://api.routeyou.com/2.0/rest/oauth/token \ -d grant_type=authorization_code \ -d client_id=<client ID> \ -d client_secret=<client secret> \ -d code=<authorization code> \ -d redirect_uri=<redirect URI>
Refreshing an expired access token (Refresh Token Grant)
Perform a POST request to https://api.routeyou.com/2.0/rest/oauth/token to refresh an expired access token.
Request parameters:
- grant_type: "refresh_token"
- client_id: The ID of your application. This is obtained during registration of the application.
- client_secret: The client secret obtained during registration. Don't pass the client secret when you can't keep it confidential (browser/native app).
- refresh_token: The refresh token received in a previous call.
Response: JSON containing the following values
- token_type: "Bearer"
- expires_in: Time before the access token expires in seconds.
- access_token: The token you will use to make API calls (see below).
- refresh_token: A new refresh token.
Example:
curl -X POST https://api.routeyou.com/2.0/rest/oauth/token \ -d grant_type=refresh_token \ -d client_id=<client ID> \ -d client_secret=<client secret> \ -d refresh_token=<refresh token>
Accessing the APIs using an access token
See JSON-RPC, but omit the token in the URL and add an Authorization header instead.
For information on how to construct a JSON-RPC request, see the Wikipedia article about JSON-RPC.
Send requests to the following URL:
https://api.routeyou.com/%service-version%/json/%service-name%
The parts between % should be replaced with the following:
%service-version%: the version of the service%service-name%: the name of the service
Include the access token by adding the Authorization: Bearer <access token> header.
Example:
curl -X POST https://api.routeyou.com/2.0/json/Route \
-H "Authorization: Bearer <access token>" \
-d '{"jsonrpc":"2.0","id":1,"method":"get","params":[44]}'