Authentication

Accessing the LanguageWire MT API requires access tokens that you must include with each request. For those, you can either start with a trial or a production account. The getting access page describes how you can generate those.

OAuth 2.0 authorization

We use the OAuth 2.0 authorization framework for all the endpoints in the API.

This is a standard protocol that provides security for our REST endpoints and it is widely used to protect access to APIs which are accessed by native applications and web applications.

All our operations require authentication that is performed on per-request basis. Such requests must include an authorization header composed according to the internal Bearer token authorization schema:

Authorization: Bearer {access token}

Bearer authentication

Bearer authentication (also called token authentication) is the HTTP authentication scheme that we apply to our API, and involves security tokens called bearer tokens. This is the most common way to access OAuth 2.0 APIs.

The bearer token is a single cryptic string, that acts as the authentication of the API request, sent in an HTTP “Authorization” header.

The following example uses cURL to retrieve information about the list of language pairs using the /v2/languages/text-translation endpoint:

curl -L -X GET 'https://mt.api.languagewire.com/v2/languages/text-translation' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer eyJhbGc.....yv7kNw'

Client credentials

When you have created your own application, you generated what is known as client credentials. Client credentials consist of a client ID (similar to a username) and client secret (similar to a password). Always store the client secret key securely; never reveal it publicly!

Caution

For production accounts, if you suspect that the secret has been compromised, regenerate it immediately by clicking the "Generate Secret" button from your account's page.

Client credentials flow

Client credentials are used as an authorization grant typically when the client is acting on its own behalf (being also the resource owner) or is requesting access to protected resources based on an authorization previously arranged with the authorization server.

In order to generate a token you just need to make a call to our identity provider server as in this example:

curl --location 'https://idp.languagewire.com/realms/languagewire/protocol/openid-connect/token' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'client_id=YOUR_CLIENT_ID' \
    --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
    --data-urlencode 'grant_type=client_credentials'

Note

The request to acquire a token uses form-encoded data (application/x-www-form-urlencoded), not JSON.

Once you do that you will receive a response like:

{
  "access_token": "eyJhbGc.....yv7kNw",
  "expires_in": 1200,
  "refresh_expires_in": 0,
  "token_type": "Bearer",
  "not-before-policy": 0,
  "scope": ""
}

Then you can use this access_token for the time in seconds it says in the expires_in. Once the token is expired, our API will no longer accept it and will return a '401 - Unauthorized' error response. After a token has expired, you can simply request a new one.

This way of generating tokens is the same for both trial and production accounts.

How to use the token

Note

After you acquire a token, store the token and reuse it for multiple API calls until it expires. There's no need to obtain a new token for each request.

You should include the access token in the HTTP request header as
Authorization: Bearer {access_token_value}.

Example for the text translation request:

import requests
import json

url = "https://mt.api.languagewire.com/v2/translate"
payload = json.dumps({
  "source": "en",
  "target": "de",
  "segments": [
    {"text": "Hello from LanguageWire!"}
  ]
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAi...'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.json())