Access token API
Available for Vipps and MobilePay.
Authorization endpoints
The following two endpoints are provided for authorization:
- Access token endpoint (for merchants):
POST:/accesstoken/get
- Token endpoint (for some APIs and some partner roles):
POST:/miami/v1/token
If you are a merchant, skip to Access token endpoint. If you are a partner, see Partner authorization.
Partner authorization
Some new APIs, including the Management API and Report API use a new token endpoint, for some roles.
Here is a description of how you, as a partner, can use the authorization endpoints:
API | Merchant: Normal API keys | Partner: Partner keys | Partner: Management keys | Partner: Accounting keys |
---|---|---|---|---|
Main APIs | POST:/accesstoken/get | POST:/accesstoken/get | POST:/accesstoken/get | N/A |
Management API | POST:/accesstoken/get | POST:/accesstoken/get | POST:/miami/v1/token : | N/A |
Report API | POST:/accesstoken/get | N/A | N/A | POST:/miami/v1/token : |
Please note:
- Please see Partner keys.
- If you are a partner and have partner keys, you use those.
- If you are a partner and have management keys, you use those.
- If you are a partner and has accounting keys, you use those.
- If you are a merchant you use your normal API keys.
- The
POST:/miami/v1/token
will be used for all new APIs, but we will not change the authentication for existing APIs. A working integration that usesPOST:/accesstoken/get
will continue to work as before. - There are technical reasons for the two endpoints and the different roles, and it's unfortunately no easy way to "streamline" this for all APIs and roles at once.
- You can have multiple access tokens, and they can be used at the same time as long as they are valid.
- Partners should always use partner keys when possible.
Access token endpoint
Use POST:/accesstoken/get
to get an authorization token that can be used with most Vipps MobilePay API requests.
All API requests must include an Authorization
header with
a JSON Web Token (JWT), which we call the access token.
The Access token API allows you to get this token.
Get an access token
The access token is obtained by calling
POST:/accesstoken/get
and providing these values in the HTTP header:
client_id
- Client_id for a sales unit.client_secret
- Client_id for a sales unit.Ocp-Apim-Subscription-Key
- Subscription key for a sales unit.
Request:
A sample request to
POST:/accesstoken/get
,
including the
HTTP headers:
client_id: fb492b5e-7907-4d83-ba20-c7fb60ca35de
client_secret: Y8Kteew6GE2ZmeycEt6egg==
Ocp-Apim-Subscription-Key: 0f14ebcab0ec4b29ae0cb90d91b4a84a
Merchant-Serial-Number: 123456
Vipps-System-Name: acme
Vipps-System-Version: 3.1.2
Vipps-System-Plugin-Name: acme-webshop
Vipps-System-Plugin-Version: 4.5.6
(Unfortunately,
POST:/accesstoken/get
is a POST
without a body, to an endpoint with
get
in the URL. Too late to change it now, sorry.)
Here's a curl
example with the same API credentials and HTTP headers as above:
curl -X POST 'https://apitest.vipps.no/accesstoken/get' \
-H "Content-Type: application/json" \
-H 'client_id: YOUR-CLIENT-ID' \
-H 'client_secret: YOUR-CLIENT-SECRET' \
-H 'Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY' \
-H 'Merchant-Serial-Number: YOUR-MSN' \
-H 'Vipps-System-Name: acme' \
-H 'Vipps-System-Version: 3.1.2' \
-H 'Vipps-System-Plugin-Name: acme-webshop' \
-H 'Vipps-System-Plugin-Version: 4.5.6' \
--data ''
Replace the value of the Vipps-System
headers with your own values.
See HTTP headers for more details.
When a partner uses
partner keys
for requests that are not for a specific merchant,
the Merchant-Serial-Number
can be omitted.
Response:
The response from
POST:/accesstoken/get
is like this:
{
"token_type": "Bearer",
"expires_in": "86398",
"ext_expires_in": "0",
"expires_on": "1495271273",
"not_before": "1495184574",
"resource": "00000002-0000-0000-c000-000000000000",
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni <truncated>"
}
An explanation of the contents of the access token (the JWT properties):
Name | Description |
---|---|
token_type | It’s a Bearer token. The word Bearer must be added before the token |
expires_in | Token expiry duration in seconds. |
ext_expires_in | Extra expiry time. Not used. |
expires_on | Token expiry time in epoch time format. |
not_before | Token creation time in epoch time format. |
resource | For the product for which token has been issued. |
access_token | The actual access token that needs to be used in Authorization request header. |
Please note: The access token is valid for 1 hour in the test environment
and 24 hours in the production environment. To be sure that you are using
correct time please use expires_in
or expires_on
.
The access token is a JWT (JSON Web Token), and uses UTC time.
You now have the access token and can make subsequent API calls with the following HTTP headers:
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni <truncated>
Ocp-Apim-Subscription-Key: 0f14ebcab0ec4b29ae0cb90d91b4a84a
Merchant-Serial-Number: 123456
Vipps-System-Name: acme
Vipps-System-Version: 3.1.2
Vipps-System-Plugin-Name: acme-webshop
Vipps-System-Plugin-Version: 4.5.6
Important: Remember to specify Bearer
. If not, you may get a
HTTP 401 Unauthorized
error. See the FAQ:
Why do I get HTTP 401 Unauthorized?
.
Token endpoint
The token endpoint is:
POST:/miami/v1/token
.
While most of the older APIs, use the access token endpoint, some new APIs, including the Management API and Report API use this token endpoint.
Important: This endpoint will be renamed to
POST:/authentication/v1/token
later, when the internal technical dependencies are resolved.
Authenticating with this endpoint is quite similar to the above-mentioned flow, but this new endpoint uses a completely standard OAuth client credentials flow, allowing use of standardized libraries. We strongly recommend this approach, using one of the trusted libraries to perform the flow. There should be no reason to implement this from scratch.
Example request to
POST:/miami/v1/token
:
curl -X POST https://api.vipps.no/miami/v1/token \
-H 'Authorization: Basic <Base64-encoded YOUR-CLIENT-ID:YOUR-CLIENT-SECRET>' \
-H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
-H 'Vipps-System-Name: acme' \
-H 'Vipps-System-Version: 3.1.2' \
-H 'Vipps-System-Plugin-Name: acme-webshop' \
-H 'Vipps-System-Plugin-Version: 4.5.6' \
--data-urlencode 'grant_type=client_credentials'
The Base64-encoded YOUR-CLIENT-ID:YOUR-CLIENT-SECRET
example is the string
with your management keys' client_id
and client_secret
encoded to Base64.
Please note: The Ocp-Apim-Subscription-Key
HTTP header should not be sent (unlike with the
POST:/accesstoken/get
endpoint).
Example (JSON) response from
POST:/miami/v1/token
:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni <truncated>",
"token_type": "Bearer",
"expires_in": 900
}