global directory of translation services
The translation workplace

Authentication API requests can be authenticated by passing an OAuth2 access token. For some apps, API keys are also supported.

OAuth2 can also be used to allow users to sign in to your website or application with their account. See supporting sign in with for details.


OAuth2 is a standard protocol for secure authorization and authentication, commonly used for RESTful APIs. It allows users to authorize your application to use on their behalf, without having to share sensitive login information.

Using OAuth2, your app acquires an access token using one of several methods, and then passes that access token in all API requests, like this:

curl -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

OAuth2 quick start

  1. Get an OAuth2 client library.
  2. Register your app at You'll be assigned a client_id and client_secret. A redirect_uri is required, but if you're not ready for that yet just put in a dummy URL like
  3. Configure your OAuth2 client library with your client_id, client_secret, and redirect_uri. Tell it to use to request authorization and to get access tokens.
  4. Make an authorized request to to test it out. See the GET: /user documentation for more information about this endpoint.

While it may be easier to use a third-party OAuth2 library, you can also write your own OAuth2 client. See below for details about the authorization flows.

Accessing the public API without an authenticated user

If your app only needs to access public data, and doesn't need to act on behalf of a particular user, get an access token that identifies only your app by using the Client Credentials Grant Type.

Example access token request using client credentials grant type:


curl \
    -d "grant_type=client_credentials"

Example response:


Pass the returned access_token in your API requests.

Accessing the API on behalf of a user

To access the API on behalf of a user (ex. to provide a "Sign in with your account" feature or to send a message from a particular user) use the Authorization Code Grant Type. This involves getting authorization from the user resulting in an authorization code, and then exchanging that authorization code for an access token.

  1. Ask the user to authorize access to their data. This is done by redirecting their browser to an authorization page at, something like this:
  2. authenticates the user and asks for permission to give access to your app.
    Here's an example of this authorization screen.
  3. If the user approves, redirects the user's browser back with an authorization code to a page in your app (the pre-configured redirect_uri). The authorization code is valid only for a short time (30 seconds as of this writing). The redirect looks something like this:
  4. Your app makes a back-channel request to exchange the authorization code for an access token. authenticates your app and issues an access token.

    curl \
        -d "grant_type=authorization_code&code=$CODE&redirect_uri=$REDIRECT_URI"


Pass the returned access_token in your API requests.

Authorization scopes

OAuth2 scopes are used to express the kind of permission you request users to authorize for your app. Different API endpoints require different authorization scopes. For example, the POST: /messages endpoint requires the message.send scope in order to send a message to other account holders on behalf of the user.

If no scope is specifically requested, all access tokens are granted public scope by default. This grants access to information that is publicly visible on the website.

To request other scopes, pass a scope parameter in the authorization request. To request multiple scopes, separate them with whitespace (URL encoded as appropriate). For example:

Token expiration and refresh tokens

Refresh tokens are issued alongside access tokens that are granted via authorization code. You can exchange the refresh token for a new access token when it expires if you want to maintain ongoing access without asking the user to re-authorize the request.

As of December 2017, access tokens expire after 14 days, and refresh tokens don't expire.

Experimenting via the Google OAuth2 Playground

One way to experiment with the whole authorization code round trip is to use the Google OAuth2 Playground.

  1. In your app settings, set your redirect_uri to
  2. Go to the Google OAuth2 Playground.
  3. Click the settings button in the top-right corner.
  4. Select "Server-side" for "OAuth flow", and "Custom" for "OAuth endpoints".
  5. Set the authorization endpoint to and the token endpoint to, select "Authorization header w/ Bearer prefix", and enter your client ID and secret.
  6. In the text field on the left, enter "public" for the scope and click "Authorize APIs". It should load the authorization screen, and once you authorize the request, return you to the Google OAuth2 Playground.
  7. Click "Exchange authorization code for tokens" to receive a token (you'll need to do this within 30 seconds). The response on the right should show the access token.
  8. Set the Request URI on the left to and click "Send the request". The response should contain data from your own profile.

Implementation notes

  • supports the Authorization Code, Client Credentials, and Implicit grant types.
  • Your app should anticipate the possibility that a granted access token might no longer work, ex. if it expires or if the user revokes access.
  • Refresh tokens are issued alongside access tokens that are granted via authorization code. You can exchange the refresh token for a new access token when it expires if you want to maintain ongoing access without asking the user to re-authorize the request.


For simple internal applications that access only public data or that act only on behalf of a single user account, an API key can be used to authenticate instead of OAuth2.

curl -H 'X-Proz-API-Key: YOUR_API_KEY'

Remember that anyone with your API key can see and change anything you have access to. You must protect it as carefully as you do your username and password.

Contact [email protected] to request an API key.

OpenID Connect

There is a basic implementation of the OpenID Connect Core protocol. To get the ID token make a request to the authorize endpoint with response_type=code id_token and include openid in your requested scope:


In response you would receive encrypted `id_token` which contains the following info:

    "iss": "https:\/\/",
    "sub": "32a9a4d0-cb6e-463f-a0ab-63d0a0418bc7",
    "aud": "724…a6",
    "iat": 1528104705,
    "exp": 1528108305,
    "auth_time": 1528104705,
    "nonce": "645125488"

`sub` is the same as UUID we use in API to retrieve user data and link users to users in your app.

There are no claims supported at the moment. If have any requests for claims support you need then contact us at [email protected]