Access to the Payway api¶
Target audience: Developers
Introduction¶
To perform actions on the API, you need an access token. This section describes the different ways your application can acquire an access token to consume the API.
To achieve this Payway builds on the ideas of the The OAuth 2.0 Authorization Framework.
Access token¶
An access token is a token that represents an identity and gives our application right to perform actions on the API. A token is issued for a specific client and has a set of scopes that determine which rights the token grants the application. An access token in Payway has a lifetime of 1 hour after which a refresh token has to be used to renew the token. As the access token enables actions to be performed on the API you must store them safely and never expose them to other applications or the user.
Client¶
An access token is connected to a client. The client uniquely identifies one integrating application i.e. each application has its own client id. The client has an id, a secret and a redirect uri.
Redirect uri¶
The redirect uri is where the user is sent once the auth request is done. The redirect uri should be protected with SSL. The redirect uri is sometimes referred to as the application's landing page.
Client secret¶
The client secret is used by your application when asking for an access token. The client secret must be be kept confidential and protected within your application.
Scopes¶
The scopes determine for which endpoints in the API the token can be used. You may only ask for the scopes that your client has been issued. The scopes are issued by Adeprimo. The required scope for each endpoint is listed in the API Documentation. In the OAuth2 spec the user should also grant access to the requested scopes for a given application. In Payway's implementation the user grant is implicit.
Example scopes
| Scope | Access type | Comment |
|---|---|---|
/external/account/r |
Read | Access to account read operations |
/external/account/w |
Write | Access to account write operations |
Different ways of obtaining an access token¶
For a web application¶
The OAuth2 Authorization Code flow is the default flow for a web application. This flow requires that you use The Payway session.
Authorization code example flow¶
- Application performs a Payway login
- User logs in if necessary and gets redirected to the redirect uri where the web-application retrieves an authorization-code
- Web-application uses the authorization-code and Client id, Client secret to fetch an access-token from Payway
- Web-application stores the access-token for the logged in user locally in a safe way
- Web-application uses the access-token to fetch account-data for the user the Payway API
- Web-application uses the refresh token to renew the access token when it has expired
Initiating the flow¶
The authorization request starts with a redirect to the Payway server's authentication endpoint with the following information:
| Field Name | Example value | Description |
|---|---|---|
| response_type | code | |
| client_id | 50fe72bb400e0351b400000e | |
| redirect_uri | https://yourdomain/landing | |
| scope | /external/me/w | one to several API scopes delimited by a space, url-encoded |
| oid | adeprimo | the id of your Payway instance |
| state | url encoded | you may use this parameter send state information you need on the landing page e.g. page where the user came from or CSRF token |
If the user is not already logged in, the user will be redirected to the login-page and when a successful login has been made, the user is redirected back to redirect_uri where the authorization-code is retrieved. You may initialize a authorization request calling the Tulo.login method using the Javascript-API or do it manually by redirecting to the Authenticate endpoint.
Using authorization-code to fetch access-token¶
On the applications Redirect uri you retrieve the "code" query-parameter and use it to fetch an access-token which in turn can be used for fetching data from Payway. Using the code received from Payway, the web-server needs to make a HTTP-POST to the Access token endpoint with the following parameters:
Request¶
- The HTTP-request must be using the POST-method.
The following headers must be set:
Content-Type: application/x-www-form-urlencoded
Accept: application/json
The parameters must be supplied in the application/x-www-form-urlencoded format in the requests body:
| Field Name | Example value | Description |
|---|---|---|
| grant_type | authorization_code | |
| code | your code | code that you captured from query string on landing page |
| client_id | 50fe72bb400e0351b400000e | |
| client_secret | your secret | |
| redirect_uri | https://yourdomain/landing |
The response from the "access_token" HTTP-POST operation is a JSON-object with the following parameters:
{
"access_token": "53837f3b400e0623bd000001",
"scope": "/external/api/v1/sso/account/r",
"token_type": "Bearer",
"expires_in" : "7200"
"refresh_token":"574190b077748c274c785a2a0a51dfa19c41958f4d6ca32b1c5e4beb8e2f7b80" //only included if enabled for you
}
For a mobile app¶
The OAuth2 Resource Owner Password Credentials flow is a good option for mobile apps where a web authentication is not possible. This flow does not require Payway session to work.
The application is responsible for collecting the user's username and password. The username and password are exchanged for an access token in a server to server call. Since the application has to deal directly with the user's password it places higher demand on the application. The password should be handled safely and not be stored.
Example:
- User clicks login
- The mobile application collects the user credentials
- The mobile application communicates with the application backend
- The application backend issues a validation request against Payway
- Payway validates the credentials and returns an access-token if valid
- The application backend stores the access-token locally in a safe manner
- The application backend fetches information about the account using the access token and returns it to the mobile application
Request¶
- The HTTP-request must be using the POST-method.
The following headers must be set:
Content-Type: application/x-www-form-urlencoded
Accept: application/json
The parameters must be supplied in the application/x-www-form-urlencoded format in the requests body:
| Field Name | Example value | Description |
|---|---|---|
| grant_type | password | |
| client_id | 50fe72bb400e0351b400000e | |
| client_secret | your secret | |
| scope | /external/me/w /external/me/r | one to several API scopes delimited by a space |
| username | adeprimo^johan@themail.com | oid and email-address separated using a "^" sign |
| password | Johan's password | the password that you have collected in your form |
The response from the "access_token" HTTP-POST operation is a JSON-object with the following parameters:
{
"access_token": "53837f3b400e0623bd000001",
"scope": "/external/me/w /external/me/r",
"token_type": "Bearer",
"expires_in" : "7200"
"refresh_token":"574190b077748c274c785a2a0a51dfa19c41958f4d6ca32b1c5e4beb8e2f7b80" //only included if enabled for you
}
Server to Server application¶
Some tasks on the API does not require the user to be authenticated. For example fetching packages or creating an account. These operations are performed by your application using an access token that is connected only to your client-id. Not to any end-user identity as with the other grant flows. Hence, if an operations involves an identity it is your responsibility to ensure that operation is performed on the right identity.
Since there is no user involvement in this flow and you can ask for a new access-token at any given time, there are no refresh tokens.
In the OAuth2 spec this flow is referred to as Client Credentials.
Request¶
- The HTTP-request must be using the POST-method.
The following headers must be set:
Content-Type: application/x-www-form-urlencoded
Accept: application/json
The parameters must be supplied in the application/x-www-form-urlencoded format in the requests body:
| Field Name | Example value | Description |
|---|---|---|
| grant_type | none | a string "none" |
| client_id | 50fe72bb400e0351b400000e | |
| client_secret | your secret | |
| scope | /external/api/campaign/w | scopes to be issued, separated by space |
Curl¶
curl --request POST \
--url https://payway-api.stage.adeprimo.se/api/authorization/access_token \
--header 'accept: application/json' \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'client_id=<client_id>&client_secret=<client_secret>&grant_type=none&scope=/external/account/r /external/account/w'
Example: * Your application makes HTTP-POST request to the access-token endpoint * Your application receives an access-token * Your application uses access-token in API-calls to Payway
{
"access_token": "3e5e7b2322bf60646b817edf00583d1651de8fdb33a19f7e446d4141df1fd240",
"scope": "/external/api/campaign/w",
"token_type": "Bearer",
"expires_in" : "7200"
}
Handling access-token expiry with refresh tokens¶
What is a refresh token?¶
A refresh token is a long lived token that can be used to get new access tokens when they expire.
Payway refresh tokens do not expire but inactive refresh tokens are removed after 180 days. When the refresh token is accessed the inactivity counter is reset and a new 180 days is added.
Your application may not be issued refresh tokens if it only has online access.
Attention
Available as of v.4.2.1.
According to RFC6749 a refresh token cannot grant a bigger scope than initially granted to the access-token.
However, since scopes are implicitly granted this presents a poor user experience when client scopes are altered or extended. This is why we have chosen to deviate from the standard and grant a bigger scope when requested, if available to the client.
How do I get one?¶
You get the refresh token in the access token response from the Authorization Code and Resource owner password credentials grant flows.
Refresh tokens have to be enabled. This is done by activating "Offline access" for the API user used. See Security => Api users in PAP.
When should I use the refresh token?¶
You should use the refresh when the expires_in has passed or you get a 401 Unauthorized together with a "expired_token" error in the "WWW-Authenticate" header when trying to access the API.
Example:
< HTTP/1.1 401 Unauthorized
< WWW-Authenticate: OAuth realm="backend.worldoftulo.com", error="expired_token", error_description="The access token has expired."
You may additionally want use the refresh token on the 401 Unauthorized error together with a "invalid_token" error in the "WWW-Authenticate" header when trying to access the API.
Example:
< HTTP/1.1 401 Unauthorized
< WWW-Authenticate: OAuth realm="backend.worldoftulo.com", error="invalid_token", error_description="The access token is no longer valid."
How do I use it?¶
Store the refresh token safely on your backend and when you need a new access token, make a HTTP-POST to the Access token endpoint with the following parameters:
| Field Name | Example value | Description |
|---|---|---|
| grant_type | refresh_token | |
| refresh_token | your token | |
| client_id | 50fe72bb400e0351b400000e | |
| client_secret | your secret | |
| scope | /external/me/w /external/me/r | you can omit this to get the same scopes as the previous access token |
| redirect_uri | your redirect uri |
The response from the "access_token" HTTP-POST operation is a JSON-object with the following parameters:
{
"access_token": "11abf75333ae42e7e337a868568a3bac0a329f094aa868d0269fd09456f0ea86",
"scope": "/external/me/r",
"token_type": "Bearer",
"expires_in" : "7200"
}
Endpoints¶
Production¶
| Name | Address |
|---|---|
| Authenticate | https://backend.worldoftulo.com/oauth2/auth |
| Access token (new endpoint) | https://backend.worldoftulo.com/api/authorization/access_token |
Stage¶
| Name | Address |
|---|---|
| Authenticate | https://payway-api.stage.adeprimo.se/oauth2/auth |
| Access token (new endpoint) | https://payway-api.stage.adeprimo.se/api/authorization/access_token |