-
- Translation help networkKudoZOther terminology resourcesLearn more: About terminology at ProZ.com
-
-
AuthenticationProZ.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. OAuth2OAuth2 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
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 userIf 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 Accessing the API on behalf of a userTo 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.
Pass the returned 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
If no scope is specifically requested, all access tokens are granted
To request other scopes,
pass a 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 tokensRefresh 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 PlaygroundOne way to experiment with the whole authorization code round trip is to use the Google OAuth2 Playground.
Implementation notes
API KeyFor 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 [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 curl https://www.proz.com/oauth/authorize?response_type=code%20id_token&scope=openid&client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI} In response you would receive encrypted `id_token` which contains the following info: { "iss": "https:\/\/www.proz.com", "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 ProZ.com 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]. |