The Phraseanet API v1 can only be accessed via oAuth2.0. OAauth2.0 allows a secure API authentication in a simple and standard way.
For PHP development, it is strongly recomended to use the Phraseanet PHP SDK. For other languages, you can find some oAuth2.0 libraries.
Note
At this time OAuth access tokens do not expire, you should be prepared for this possibility in the future. Also remember that a user may revoke access via the Phraseanet settings page at any time.
For OAuth 2.0, all applications need to register their name and callback URL in Phraseanet to get their API credentials.
From this registration process Phraseanet provides the “Client ID” and “Client Secret”.
The registration is done in the account settings. You can access this page by clicking your login in the menubar of Phraseanet.
There are three ways to use the API.
Developer must Redirect end-user to the authorize endpoint with the following query parameters :
mandatory string - The client ID received from Phraseanet on registration.
optional string - The client secret received from Phraseanet on registration.
mandatory string - One of the available response types.
mandatory string - The same redirect URI you provided on registration.
optional string - An unguessable random string. It is used to protect against cross-site request forgery attacks.
End-user authenticates on Phraseanet and the browser is redirected to the redirect_uri callback.
https://SERVER_NAME/api/oauthv2/authorize
?client_id=YOUR_CLIENT_ID
&response_type=code
&redirect_uri=YOUR_REGISTERED_REDIRECT_URI
If authentication succeed, a code parameter is available in the URI, alongside the state parameter (if provided). If authentication failed, an error parameter is available.
Example of successful URI :
https://example.com/callback/?code=49ce2762ff5413607ae936b2ca6e409e
Example of errored URI :
https://example.com/callback/?error=Invalid+user
Once the developer has a code, he must exchange it to an oauth_token using the token endpoint. Whereas the previous step is an interaction between the end-user and Phraseanet, this exchange is done server side.
Parameters for the token endpoint are as follow :
mandatory string - The client ID received from Phraseanet on registration.
optional string - The client secret received from Phraseanet on registration.
mandatory string - One of the available grant types.
mandatory string - The same redirect URI you provided on registration.
mandatory string - The code returned on a successful call to the authorize end point.
https://SERVER_NAME/api/oauthv2/token
?client_id=YOUR_CLIENT_ID
&grant_type=authorization_code
&redirect_uri=YOUR_REGISTERED_REDIRECT_URI
&code=CODE
The response is JSON
{
access_token: YOUR_ACCESS_TOKEN
}
Redirect users who wish authenticate to
https://SERVER_NAME/api/oauthv2/authorize
?client_id=YOUR_CLIENT_ID
&response_type=token
&redirect_uri=YOUR_REGISTERED_REDIRECT_URI
If the user accepts, he is redirected back to
https://YOUR_REGISTERED_REDIRECT_URI/#access_token=ACCESS_TOKEN
This flow is meant for mobile and desktop installed applications that want access to user data.
The native app flow is identical to the server-side flow with one exception: a special redirect_uri. Instead of specifying an URL on your site, use the special string: urn:ietf:wg:oauth:2.0:oob. The “oob” part stands for “out of band” and the rest of the string identifies it as a part of the OAuth 2.0 standard.
When you use this redirect_uri, instead of redirecting the user’s browser to a page on your site with an authorization code, Phraseanet displays the authorization code or error response in a text field with instructions for the user to copy and paste it in to your application.
https://SERVER_NAME/api/oauthv2/authorize
?client_id=YOUR_CLIENT_ID
&redirect_uri=urn:ietf:wg:oauth:2.0:oob
&response_type=code
You can use your access token to call a protected API by including it in an oauth_token query parameter or an Authorization header in all available endpoint. For example :
curl https://SERVER_NAME/api/v1/baskets/list/?oauth_token=YOUR_ACCESS_TOKEN
To obtain an access token, you can use the resource owner password credentials. (i.e. a username and password)
This method eliminates the need for the client to store the resource-owner’s credentials for future use.
Warning
This method should only be used when there is a high degree of trust between the resource owner and the client.
See also
https://SERVER_NAME/api/oauthv2/token
?client_id=YOUR_CLIENT_ID
&grant_type=password
&username=johndoe
&password=A3ddj3w