OAuth 2.0: Best Practices
We are very serious about the privacy of our customers. When we grant access to our APIs, we expect you to take our customers’ privacy just as seriously as we do.
We use OAuth 2.0 authentication protocol to ensure that applications on our platform are safe and easy to use.
Ensure your application follows these best practices.
All requests to our authentication servers must be made over HTTPS to prevent man-in-the-middle attacks. Additionally, OAuth 2.0 requests require you to use HTTPS. Your app should also ideally be hosted on a secure server.
Client ID and secret
The Client ID is a public identifier of your application. The Client secret is confidential and should only be used to authenticate your application and make requests to apaleo’s APIs.
When you exchange an OAuth 2.0 authorization code for an access token, the Client secret is passed as part of the request. Ensure that you do not expose this request publicly.
OAuth access tokens
OAuth 2.0 tokens are entrusted to you by users who give you permission to act and access data on their behalf. Using access tokens, you can access a user’s private information through the apaleo APIs. To keep access tokens safe:
- When making calls, always pass access tokens over a secure (HTTPS) connection.
- Do not discard your OAuth token after one-time use. API calls to retrieve an OAuth token are rate-limited per application. To avoid hitting your call limit, cache, and re-use tokens until the expiration time. For more information, see OAuth 2.0: Refresh token grant flow.
Thwart cross-site request forgery (CSRF) attacks
Your app can use a
state parameter to ensure that the response belongs to a request initiated by
the same user, therefore preventing CSRF attacks. If the
state does not match, it means that there
could be a possible redirect by a malicious attacker. For more information, see
The redirect URI must adhere to RFC 6749 Section 3.1.2. The URI must meet the following conditions:
- Must use HTTPS
- URLs must be an absolute URI. For example,
- URL arguments are ignored. For example,
https://example.com/?id=1is the same as
- URLs cannot include a #. For example,
If you are requesting scopes, make sure that you only request what you absolutely need. When you do this, you are more likely to gain user consent when required because users are more likely to authorize access for limited, clearly-specified scopes.
If you are using OpenID Connect enabled app, then you need to use the following standard scopes.
|A mandatory scope that returns a
sub claim, which represents a unique identifier for the authenticated user.
|This scope requests access to the end-user’s default profile claims.
scope variable as a set of case-sensitive and space-delimited strings as follows:
scope: 'offline_access availability.read reservations.read'
In an OpenID Connect implementation:
scope: 'offline_access openid profile availability.read identity:account-users.read rates.read reservations.read'
The error codes and their descriptions are well documented in the OAuth2 RFC, such as Code Grant Errors.
Authorization response error codes
|This error is typically due to a required parameter missing from the request. For example, omitting the response_type parameter would raise this error.
|Check whether all the parameters are correct,
client_id exists, and so on.
|Your app is not authorized to request an authorization code using this grant method. The
redirect_URI is either incorrect or not provided.
|Make sure that the provided
redirect_URI is correct, and at least one
redirect_uri is defined in the client app.
|apaleo does not support obtaining an authorization code using this method.
|Try to change the selected method of authorization.
|If your app requests invalid, unknown, or malformed scope.
|Make sure that the request is correct.
Token response error codes
|The request repeats a parameter, misses a required parameter, includes an unsupported parameter value (other than grant type), utilizes more than one mechanism for authenticating the client, or is otherwise malformed.
|Check the response header and request.
|Client authentication failed. For example, there’s no such client with that
|The Refresh token has been revoked. The authorization code has been already consumed or does not exist.
|Client is not allowed for code grant flow or for refreshing tokens.
|The authorization grant type is not supported by apaleo.