ProZ.com global directory of translation services
The translation workplace
Ideas

Authentication

ProZ.com 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 ProZ.com account. See supporting sign in with ProZ.com for details.

OAuth2

OAuth2 is a standard protocol for secure authorization and authentication, commonly used for RESTful APIs. It allows users to authorize your application to use ProZ.com 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' https://api.proz.com/v2/freelancer/me

OAuth2 quick start

  1. Get an OAuth2 client library.
  2. Register your app at ProZ.com. 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 https://example.com.
  3. Configure your OAuth2 client library with your client_id, client_secret, and redirect_uri. Tell it to use https://www.proz.com/oauth/authorize to request authorization and https://www.proz.com/oauth/token to get access tokens.
  4. Make an authorized request to https://api.proz.com/v2/user 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:

YOUR_CLIENT_ID=102123192c77a55c7856b65904fd941e6ac6d081
YOUR_CLIENT_SECRET=c2339accfcb0d86ff460cb32270b50f5526540fd

curl https://www.proz.com/oauth/token \
    -u $YOUR_CLIENT_ID:$YOUR_CLIENT_SECRET \
    -d "grant_type=client_credentials"

Example response:

{
  "access_token":"725caaba2ea8aaa364b91c5e1fbfbd132c9ed8f6",
  "expires_in":1209600,
  "token_type":"Bearer",
  "scope":"public"
}

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 ProZ.com 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 ProZ.com, something like this:
    Location: https://www.proz.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=code
    
  2. ProZ.com 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, ProZ.com 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:
    Location: https://example.com/?code=18db1accfcb0d86ff460cb32270b50f55265fd40
    
  4. Your app makes a back-channel request to exchange the authorization code for an access token. ProZ.com authenticates your app and issues an access token.

    CODE=18db1accfcb0d86ff460cb32270b50f55265fd40
    CLIENT_ID=102123192c77a55c7856b65904fd941e6ac6d081
    CLIENT_SECRET=c2339accfcb0d86ff460cb32270b50f5526540fd
    REDIRECT_URI=https://example.com
    
    curl https://www.proz.com/oauth/token \
        -u $CLIENT_ID:$CLIENT_SECRET \
        -d "grant_type=authorization_code&code=$CODE&redirect_uri=$REDIRECT_URI"
    

    Response:
    {
      "access_token":"725caaba2ea8aaa364b91c5e1fbfbd132c9ed8f6",
      "expires_in":1209600,
      "token_type":"Bearer",
      "scope":"public",
      "refresh_token":"82120da400de733549ca031dbb23888ac6acff9d"
    }
    

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 ProZ.com 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 ProZ.com 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:

https://www.proz.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=code&scope=public+message.send

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 https://developers.google.com/oauthplayground.
  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 https://www.proz.com/oauth/authorize and the token endpoint to https://www.proz.com/oauth/token, 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 https://api.proz.com/v2/freelancer/me and click "Send the request". The response should contain data from your own ProZ.com profile.

Implementation notes

  • ProZ.com 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.

API Key

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

curl -H 'X-Proz-API-Key: YOUR_API_KEY' https://api.proz.com/v2/freelancer/32a9a4d0-cb6e-463f-a0ab-63d0a0418bc7

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 api@proz.com to request an API key.