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.

Use HTTPS

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.

Do not distribute Client secrets in email, distributed native applications, client-side JavaScript, or public code repositories. Do not store it in files on a web server that can be viewed externally. For example, configuration files, include files, log files, etc.

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:

Do not store them in insecure or easily accessible locations. Client-side files, such as JavaScript or HTML files, should never be used to store sensitive information, as these can easily be accessed.
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 RFC-6749.

Redirect URIs

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, https://example.com/auth/callback, not /auth/callback.
URL arguments are ignored. For example, https://example.com/?id=1 is the same as https://example.com/.
URLs cannot include a #. For example, https://example.com/auth/callback#mycat is invalid.

Scopes

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.

Scope	Description
`openid`	A mandatory scope that returns a `sub` claim, which represents a unique identifier for the authenticated user.
`profile`	This scope requests access to the end-user’s default profile claims.

Always pass 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'

Error handling

The error codes and their descriptions are well documented in the OAuth2 RFC, such as Code Grant Errors.

Authorization response error codes

Error code	Description	Solution
`invalid_request`	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.
`unauthorized_client`	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.
`unsupported_response_type`	apaleo does not support obtaining an authorization code using this method.	Try to change the selected method of authorization.
`invalid_scope`	If your app requests invalid, unknown, or malformed scope.	Make sure that the request is correct.

Token response error codes

Definition of errors of issuing Access Token in the RFC6749 standard

Error code	Description	Solution
`invalid_request`	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.
`invalid_client`	Client authentication failed. For example, there’s no such client with that `client_id` and `client_secret`.
`invalid_grant`	The Refresh token has been revoked. The authorization code has been already consumed or does not exist.
`unauthorized_client`	Client is not allowed for code grant flow or for refreshing tokens.
`unsupported_grant_type`	The authorization grant type is not supported by apaleo.