Back to top image

Authentication

To use the Smartling API you first authenticate using the credentials from your API Token. This returns an access token which you include in subsequent requests. This is described in more detail below.

API Token

API tokens contain the credentials (user identifier and user secret) that are required to authenticate to the API. They can be scoped to an entire Smartling account, or to a particular project. Project-specific tokens are recommended, particularly during development and testing.

API tokens can be re-used as needed–they don't expire. However, it's simple to delete them and create new ones if required, for example if the user secret was compromised.

To obtain a token for your Smartling project, follow these steps.

Copy the token secret and store in a secure location. Once you navigate away from this page it won't be accessible again.

The data you need to use the API are:

  • Project ID
  • Account ID
  • User Identifier
  • User Secret

The account ID, project ID and user identifier are always available from the API page, but the user secret is not.

Authentication API

Once you have your API token credentials, you can use the Authenticate API endpoint to obtain an access token. This endpoint takes the user identifier and user secret from the API token as parameters and, if authentication is successful, returns an access token to be used for subsequent API calls. An example authentication response is shown below:

{
    "response": {
        "code": "SUCCESS",
        "data": {
            "accessToken": "b816424c-2e95-11e7-93ae-92361f002671",
            "expiresIn": 480,
            "refreshExpiresIn": 3660,
            "refreshToken": "c0a6f410-2e95-11e7-93ae-92361f002671",
            "tokenType": "Bearer"
        }
    }
}

(Note: real access and refresh tokens are much longer than the example shown above.)

The access token should be saved by your code and reused in subsequent API requests as described next. 

Using the access token

All API endpoints, except for Authenticate and Refresh access token require a valid access token to be included in an HTTP header of the following format:

Authorization: Bearer ACCESSTOKEN

where ACCESSTOKEN is replaced with the actual access token returned by the Authenticate or Refresh access token calls.

Refreshing the access token

Access tokens expire after approximately 5-10 minutes and need to be refreshed before this happens. For various reasons, including performance, it is preferable to refresh an access token before it expires rather than call the Authenticate endpoint again.

Before your access token expires, call the Refresh access token endpoint to obtain a new one without having to re-authenticate.

This refresh logic is expressed in pseudo code below:

getAccessToken()
    if saved access token exists and is not expired
        return saved access token
        
    else if saved refresh token exists and has not expired
        refresh access token
        save and return new access token

    else 
        authenticate
        save and return new access token

You can continue to refresh access tokens until the refresh token expires, which typically happens after 6-24 hours. When your refresh token expires, your application needs to call the Authenticate endpoint again.

Table of Contents