OAuth 2 flow

Learn about Lokalise OAuth 2 flow.

Developers can build their own applications to manage user data in Lokalise using the OAuth 2 authentication flow.

With the OAuth 2 authentication, an application can make requests to Lokalise APIv2 on behalf of a user.

OAuth 2 is an authorization protocol that allows a user to grant third-party applications access to their information on another site.

Authorization flow

This process can be separated into three stages:

  • The user requests an access code.
  • The user makes a request with the access code and receives an access token. The user can receive data from Lokalise with this access token.
  • After the access token expires the user makes a request to refresh the token.

The authorization flow is shown in more detail in the following diagram:

11401140

Register a new application

To register your app with Lokalise, you should contact our support team and provide the following information:

  • Title of your application
  • Logo of your application
    • Supported size is 150x150px.
    • Supported formats are PNG and JPG.
  • Description of your application (this field is optional).
  • Link to app website/documentation (this field is optional).
  • Required scopes. Find the list required scopes for the corresponding API endpoints in the Lokalise API description.

OAuth 2 authorization overview

Lokalise is using OAuth 2.0 authorization protocol implementation of authorization code flow.

Prerequisites

  • The app should be registered with Lokalise.
  • OAuth 2 client ID ("Client ID") and OAuth 2 client secret ("Client Secret") should be obtained.
  • You should have a publicly available URL where the user will be redirected after the authentication ("Redirect URI").

Step 1. Obtain Authorization Code

The app should redirect users to the auth URL. After a successful authorization users are forwarded to the redirect URL with the authorization code as a parameter.

The request should be sent to the following URL: https://app.lokalise.com/oauth2/auth

URL parameters for the GET request:

ParameterExplanation
client_idThe App Client ID received after registration
redirect_uriThe URL in your application where users will be sent after authorization.
scopeOne or more scopes the app requires. Multiple scopes should be separated with spaces.
stateA random string used for protection against CSRF attacks. (Optional if you are not using redirect_uri)

Here's an example request:

https://app.lokalise.com/oauth2/auth?client_id=SomeClientID&redirect_uri=https://example.com/auth/success&scope=write_projects+read_keys&state=someRandomStateString

After successfully logging in, users will be redirected to the following URL:

https://example.com/auth/success?code=123abc

Step 2. Obtain access token

The app can use the authorization code received in the previous step to obtain the access token. To achieve that, the app should send a POST request to the access token URL.

URL parameters for the POST request:

ParameterExplanation
grant_typeSpecifies action to be taken (should be authorization_code)
client_idThe app client ID received after registration
client_secretThe app client secret received after registration
codeThe code received after successful user authentication and redirect

Here's an example request with cURL:

curl -X POST \
  https://app.lokalise.com/oauth2/token \
  -H "content-type: application/json" \
  -d "{     
        \"grant_type\":\"authorization_token\",
        \"client_id\":\"SomeClientID\",
        \"client_secret\":\"SomeClientSecret\",
        \"code\":\"yourCode\"
  }"

A successful response should contain the following data:

ParameterExplanation
access_tokenAccess token to use for request authentication
refresh_tokenRefresh token to use to obtain new access token after the current expires.
expires_inAmount of seconds until the access token expires (Usually, 1 hour)
token_typeThe authorization token type used. Will be required for authenticated requests. (Usually, "Bearer").

Here's an example:

{
  "access_token":"someAccessToken",
  "refresh_token":"someRefreshToken",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Step 3. Make requests to the API

The app now can make requests to Lokalise API on behalf of the authorized user. In order to authorize a request, the Authorization request header must contain the token type and the actual access token.

Here's a sample request with cURL:

curl -H "Authorization: Bearer someAccessToken" https://api.lokalise.com/api2/projects

Step 4. Use refresh token

For security reasons, the access token has a relatively short expiration time (usually, 1 hour). In order to prevent your users from the need to reauthorize the app after the token expiration, the app can obtain new access token using refresh token.

The app should send a POST request to the access token URL with the following parameters:

ParameterExplanation
grant_typeSpecifies action to be taken. (Should be refresh_token).
client_idThe App Client ID received after registration.
client_secretThe App Client Secret received after registration.
refresh_tokenThe refresh token obtained with "authorization_code" request

Here's a sample request with cURL:

curl -X POST \
  https://app.lokalise.com/oauth2/token \
  -H "content-type: application/json" \
  -d "{
        \"grant_type\":\"refresh_token\",
        \"client_id\":\"SomeClientID\",
        \"client_secret\":\"SomeClientSecret\",
        \"refresh_token\":\"someRefreshToken\"
  }"

A successful response should contain the following data:

ParameterExplanation
access_tokenAccess token to use for request authentication
scopeOne or more scopes the token has access to
expires_inAmount of seconds until the access token expires (usually, 1 hour)
token_typeThe authorisation token type used. Will be required for authenticated requests. (usually, "Bearer").

Here's an example response:

{
  "access_token":"someAccessToken",
  "scope":"write_projects",
  "expires_in": 3600,
  "token_type": "Bearer"
}

OAuth 2 request errors

If an OAuth 2 request results in an error, the response will an HTTP status code 400 and the body will contain a JSON object with the following fields:

FieldExplanation
errorError name
error_descriptionError description
state(Optional) The state string added on the Authorization code request

Here's an example:

{
  "error":"invalid_request",
  "error_description":"Invalid post body",
  "state":"someRandomStateString"
}

Examples

You can find sample apps utilizing OAuth 2 flow in the corresponding section.