openapi: 3.0.0
info:
  description: >-
    The Access token API is for requesting an access token, which is a JWT (JSON
    Web Token).


    There are two endpoints:


    1. `POST:/accesstoken/get`: (Standard authentication) Used by most APIs, and
    has been in use for several years.

    2. `POST:/miami/v1/token`: (Partner specialized authentication) for partners
    with limited, specialized use. Possible expansion in the future.


    For `POST:/accesstoken/get`:

    The access token must be provided in all API requests, together with the
    subscription key.

    The access token is valid for 1 hour in the test environment and

    24 hours in the production environment.


    For `POST:/miami/v1/token`:

    The access token must be provided in all API requests (no subscription key
    needed).

    The access token is valid for 15 minutes in both the test environment and
    the production environment.


    See the [Access token API guide](/docs/APIs/access-token-api) for more
    details.
  version: 2.0.0
  title: Access token
tags:
  - name: Authorization Service
    description: The primary authorization service for Vipps MobilePay APIs.
  - name: Token endpoint
    description: A token authorization for partners in certain roles.
servers:
  - url: https://api.vipps.no
    description: >-
      Production environment (uses the production API keys, the official app and
      live data)
  - url: https://apitest.vipps.no
    description: Test environment (uses the test API keys, the test app and test data)
paths:
  /accesstoken/get:
    post:
      tags:
        - Authorization Service
      summary: Request an access token (JWT bearer token)
      parameters:
        - name: client_id
          in: header
          description: >-
            The `client_id` is available on portal.vippsmobilepay.com, under the
            *Developer* section.

            Think of it as the "username".
          required: true
          schema:
            type: string
            format: guid
          example: fb492b5e-7907-4d83-ba20-c7fb60ca35de
        - name: client_secret
          in: header
          description: >-
            The `client_secret` is available on portal.vippsmobilepay.com, under
            the *Developer* section.

            Think of it as the "password".

            Keep it secret.

            We will never ask for it, and we don't need it for anything.
          required: true
          schema:
            type: string
          example: Y8Kteew6GE2ZmeycEt6egg==
        - $ref: '#/components/parameters/Ocp-Apim-Subscription-Key'
        - $ref: '#/components/parameters/Merchant-Serial-Number'
        - $ref: '#/components/parameters/Vipps-System-Name'
        - $ref: '#/components/parameters/Vipps-System-Version'
        - $ref: '#/components/parameters/Vipps-System-Plugin-Name'
        - $ref: '#/components/parameters/Vipps-System-Plugin-Version'
      description: >-
        This is an authentication endpoint for merchant use.

        The access token endpoint is used to get the JWT (JSON Web Token) that

        must be passed in every API request in the `Authorization` header.

        The access token is a base64-encoded string value that must be

        acquired first before making any Vipps MobilePay API calls.

        The access token is valid for 1 hour in the test environment

        and 24 hours in the production environment.

        For more details, see [Standard
        authentication](/docs/APIs/access-token-api/standard-authentication/).
      operationId: fetchAuthorizationTokenUsingPost
      responses:
        '200':
          description: OK
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/AuthorizationTokenResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '500':
          description: Server error.
  /miami/v1/token:
    post:
      summary: Request an access token
      tags:
        - Token endpoint
      operationId: fetchToken
      description: >-
        This is a token endpoint for partners in certain roles.

        This is based on OAuth (Open Authorization) and requires only
        `client_id` and `client_secret`.

        The `Ocp-Apim-Subscription-Key` is not used.

        *Important:* This endpoint will be renamed to `/authentication/v1/token`
        later,

        when the internal technical dependencies are resolved.

        For more details, see [Partner specialized
        authentication](/docs/APIs/access-token-api/partner-authentication/).
      parameters:
        - name: Authorization
          in: header
          description: >-
            The string 'client_id:client_secret' encoded to Base64 with Basic in
            front
          required: true
          schema:
            type: string
          example: >-
            Basic
            OTY1OGY0ZTItMjZhOC00MzQzLTliNzUtNjdhZTkzODAyMzJkOlk4S3RlZXc2R0UyWm1leWNFdDZlZ2c9PQ==
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded; charset=utf-8:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  enum:
                    - client_credentials
                  example: client_credentials
      responses:
        '200':
          description: OK
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '500':
          description: Server error.
components:
  schemas:
    TokenResponse:
      description: >-
        This _new_ accesstoken endpoint is used to get the JWT (JSON Web Token)
        that

        must be passed in every API request in the `Authorization` header.

        The access token is a base64-encoded string value that must be

        acquired first before making any Vipps MobilePay API calls.

        The access token is valid for 15 minutes both in the test environment

        and in the production environment.

        See: https://developer.vippsmobilepay.com/docs/APIs/access-token-api/
      type: object
      required:
        - access_token
        - token_type
        - expires_in
      properties:
        token_type:
          type: string
          description: |-
            The type for the access token.
            This will always be `Bearer`.
          example: Bearer
        expires_in:
          type: string
          description: >-
            Token expiry time in seconds. The token is currently valid for 15
            minutes.
          example: 900
        access_token:
          type: string
          description: The access token itself, typically 1000+ characters.
          example: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni <truncated>
    AuthorizationTokenResponse:
      type: object
      required:
        - token_type
        - expires_in
        - ext_expires_in
        - expires_on
        - not_before
        - resource
        - access_token
      properties:
        token_type:
          type: string
          description: |-
            The type for the access token.
            This will always be `Bearer`.
          example: Bearer
        expires_in:
          type: string
          description: |-
            Token expiry time in seconds.
            The access token is valid for 1 hour in the test environment
            and 24 hours in the production environment.
          example: 3600
        ext_expires_in:
          type: string
          description: Extra time added to expiry time. Currently disabled.
          example: 3600
        expires_on:
          type: string
          description: Token expiry time in epoch time format.
          example: 1547823408
        not_before:
          type: string
          description: Token creation time in epoch time format.
          example: 1547819508
        resource:
          type: string
          description: |-
            A common resource object.
            Not used in token validation.
            This can be disregarded.
          example: 00000002-0000-0000-c000-000000000000
        access_token:
          type: string
          description: |-
            The access token itself.
            It is a base64-encoded string, typically 1000+ characters.
            It can be decoded on https://jwt.io, and using standard libraries.
            See the documentation for details.
          example: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni <truncated>
  parameters:
    Merchant-Serial-Number:
      name: Merchant-Serial-Number
      in: header
      required: false
      schema:
        type: string
        pattern: ^[0-9]{4,6}$
        minLength: 4
        maxLength: 7
        example: '123456'
      description: >-
        The merchant serial number (MSN) for the sales unit. The
        Merchant-Serial-Number header

        can be used with all API keys, and can speed up any trouble-shooting of
        API

        problems quite a bit.
    Ocp-Apim-Subscription-Key:
      name: Ocp-Apim-Subscription-Key
      in: header
      required: true
      schema:
        type: string
        example: da7d5b0e18a84aeda961c0c31b75c2a9
      description: >-
        The subscription key for a sales unit. See [API
        keys](/docs/knowledge-base/api-keys/).
    Vipps-System-Name:
      name: Vipps-System-Name
      in: header
      description: |-
        The name of the ecommerce solution.
        One word in lowercase letters is good.
        See [http-headers](/docs/knowledge-base/http-headers).
      schema:
        type: string
        maxLength: 30
        example: WooCommerce
    Vipps-System-Version:
      name: Vipps-System-Version
      in: header
      description: |-
        The version number of the ecommerce solution.
        See [http-headers](/docs/knowledge-base/http-headers).
      schema:
        type: string
        maxLength: 30
        example: 5.4.0
    Vipps-System-Plugin-Name:
      name: Vipps-System-Plugin-Name
      in: header
      description: |-
        The name of the ecommerce plugin (if applicable).
        One word in lowercase letters is good.
        See [http-headers](/docs/knowledge-base/http-headers).
      schema:
        type: string
        maxLength: 30
        example: woocommerce-payment
    Vipps-System-Plugin-Version:
      name: Vipps-System-Plugin-Version
      in: header
      description: |-
        The version number of the ecommerce plugin (if applicable).
        See [http-headers](/docs/knowledge-base/http-headers).
      schema:
        type: string
        maxLength: 30
        example: 1.4.1
