Skip to content

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

Authorization code flow example

  • 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