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. Be sure to copy the token secret and store it in a secure location. Once you navigate away from the confirmation page, it cannot be accessed again. 

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:

If the Authenticate request fails unexpectedly despite using valid credentials, verify whether your account has an IP allowlist configured and whether the request originates from an allowed IP address.

{
    "response": {
        "code": "SUCCESS",
        "data": {
            "accessToken": "eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiJkMTdkMmEwMC0y...",
            "expiresIn": 480,
            "refreshExpiresIn": 3660,
            "refreshToken": "eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiJlMjhmM2I5Yy0y...",
            "tokenType": "Bearer"
        }
    }
}

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

Session lifespan

Every access/refresh token pair is tied to a single session, which has a maximum lifespan of 12 hours, regardless of how many times the tokens are refreshed.

As the session approaches this limit, refreshing the tokens returns a new access/refresh token pair with expiration times limited to the remaining session duration, rather than the standard expiresIn and refreshExpiresIn values. If you continue refreshing until the session expires, API requests will eventually fail with a 401 Unauthorized response, even if the refresh token has not yet expired.

If the refreshExpiresIn value becomes progressively shorter with each refresh, it indicates that the session is nearing its end. Instead of continuing to refresh the tokens, call the Authenticate endpoint again with your userIdentifier and userSecret to start a new session.