> **Description:** Learn how to use partner API keys to authenticate and manage Login API integrations on behalf of multiple merchants.

# Partner keys

We offer
[Partner keys](https://developer.vippsmobilepay.com/docs/partner/partner-keys.md)
which allow partners to make API calls on behalf of their merchants.

If you are a Vipps MobilePay partner managing integrations on behalf of merchants, you can use your partner API credentials to authenticate, and then send the Merchant Serial Number (MSN) to identify which of your merchants you are acting on behalf of.

**About partner keys**

Read more about partner verification in:

* [Partner keys](https://developer.vippsmobilepay.com/docs/partner/partner-keys.md)
* [Access Token API guide](https://developer.vippsmobilepay.com/docs/APIs/access-token-api/standard-authentication.md)

 Partner API keys are only functional in the production environment, not the test environment.

## Key differences between partner keys and sales unit keys in Login

The main differences between partner key integration and merchant integration are:

1. **Authentication**:
   * **Merchant integration**: Authentication is based on the Login access token, as described in the [Access token](https://developer.vippsmobilepay.com/docs/APIs/login-api/api-guide/core-concepts.md#access-token) section.
   * **Partner key integration**:
     * A token is obtained from the [`POST:/accesstoken/get`](https://developer.vippsmobilepay.com/redocusaurus/access-token-swagger-id.yaml) endpoint.
       This authorization method *must* be used because the endpoints `token_endpoint_authentication` methods used by merchants are **not supported** for partner key integrations.
     * The token is passed as a Bearer token in the header:

       ```text
       Authorization: Bearer <access-token>
       ```

2. **Merchant identification**:
   * For partner key integration, the `Merchant-Serial-Number` header **must** be included in backend requests to identify the merchant you are acting on behalf of.

**NOTE**

The target client must be configured with `client_secret_basic` authentication, although the partner themselves must use a standard access token.

See [Portal: How to set up Login for your sales unit](https://developer.vippsmobilepay.com/docs/knowledge-base/portal.md#how-to-set-up-login-for-your-sales-unit).

### Partner key when integrating from a website

This is a partner version of the [Integrate from a website](https://developer.vippsmobilepay.com/docs/APIs/login-api/api-guide/browser-flow-integration.md) flow.

#### Authorization endpoint

To initiate a login as partner, redirect the end-user's browser to a `/auth` URL containing the merchant serial number as a `msn` query parameter instead of `client_id`.

```text
GET https://api.vipps.no/access-management-1.0/access/oauth2/auth?msn={Merchant-Serial-Number}&response_type=code&scope={scopes}&state={state}&redirect_uri={redirect_uri}
```

This request will return a redirect to a `/auth` URL where the `msn` query parameter is replaced by the merchant's `client_id`

#### Token endpoint

For the `/token` endpoint, you should authenticate using an access token. Regular `client_secret_basic` or `client_secret_post` does not work for partner key integration.
The target client must be configured with `client_secret_basic` authentication.

1. Fetch [access_token](https://developer.vippsmobilepay.com/redocusaurus/access-token-swagger-id.yaml)
2. Use the access token in the `Authorization` header, `Bearer access-token`.
3. Add the `Merchant-Serial-Number` header with the target merchant serial number.

**Example request:**

```text
POST https://api.vipps.no/access-management-1.0/access/oauth2/token
Authorization: Bearer <access-token>
Content-Type: application/x-www-form-urlencoded
Merchant-Serial-Number: 12345

grant_type=authorization_code&code={authorization_code}&redirect_uri={redirect_uri}
```

### Partner key in merchant-initiated login flow

This is a partner version of the [Merchant-initiated login](https://developer.vippsmobilepay.com/docs/APIs/login-api/api-guide/merchant-initiated-login-integration.md) flow.
This works for both the [regular flow](https://developer.vippsmobilepay.com/docs/APIs/login-api/api-guide/merchant-initiated-login-integration.md#complete-login-in-the-vipps-or-mobilepay-app) and [Redirect to browser](https://developer.vippsmobilepay.com/docs/APIs/login-api/api-guide/merchant-initiated-login-integration.md#redirect-to-browser).

The `Merchant-Serial-Number` header must be sent in the header of all API requests.

1. Fetch [access_token](https://developer.vippsmobilepay.com/redocusaurus/access-token-swagger-id.yaml)
2. Use the access token in the `Authorization` header `Bearer access-token`
3. Add the `Merchant-Serial-Number` header with the target merchant serial number

**Example `/backchannel/authentication` request**

```text
POST https://api.vipps.no/vipps-login-ciba/api/backchannel/authentication
Authorization: Bearer <access-token>
Content-Type: application/x-www-form-urlencoded
Merchant-Serial-Number: 12345

scope=name address openid&login_hint=urn:msisdn:{msisdn}&state=13821s837213bng26e2n61gege26&nonce=21hebdhwqdb7261bd1b23
```

**Example `/token` request (without redirect)**

For the subsequent token request you should authorize with the same access token and add the `Merchant-Serial-Number` header as in the `/backchannel/authentication` request.

```text
POST https://apitest.vipps.no/access-management-1.0/access/oauth2/token
Authorization: Bearer <access-token>
Content-Type: application/x-www-form-urlencoded
Merchant-Serial-Number: 12345

auth_req_id=<auth-req-id>&grant_type=urn:openid:params:grant-type:ciba
```

## ID token validation

When acting as a partner on behalf of a merchant's sales unit, you don't have access to the merchant's `client_id`, which is used for [ID token validation](https://developer.vippsmobilepay.com/docs/APIs/login-api/api-guide/core-concepts.md#id-token).

It is important to validate the Id-token before using any data contained in it.
See the OIDC standard on
[Id-token validation](https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation)
for the specifics. We recommend that you use a library for this. A good place
to start is finding a library for your language at [jwt.io](https://jwt.io/#libraries-io).

We strongly encourage partners to use the `msn` claim in the ID token for this purpose and ensure that its value is the same as the Merchant Serial Number used for the login.

## Requirements

The target client must be configured with `client_secret_basic` authentication.
The partner themselves must use a standard access token.

See [Portal: How to set up Login for your sales unit](https://developer.vippsmobilepay.com/docs/knowledge-base/portal.md#how-to-set-up-login-for-your-sales-unit).

## Merchant Serial Number (MSN)

This is a unique identifier for the sales unit. This is a required parameter if you are a partner making API requests on behalf of a merchant. Use the merchant's MSN, not the partner's MSN.

See: [How to find the Merchant Serial Number](https://developer.vippsmobilepay.com/docs/knowledge-base/portal.md#how-to-find-the-merchant-serial-number).

## Userinfo

For fetching user information, the token received during the [login flow](https://developer.vippsmobilepay.com/docs/APIs/login-api/api-guide/user-info.md) must be used.

> **Full site overview:** For every page in this documentation, read [https://developer.vippsmobilepay.com/llms.txt](https://developer.vippsmobilepay.com/llms.txt).