> **Description:** Get started quickly with implementing the Login API in your application with this step-by-step guide. # Quick start This guide takes you through the essential Login API requests. ## Before you begin Sign up as an organization with Vipps MobilePay and get your API keys. You will need the [sales unit API keys](https://developer.vippsmobilepay.com/docs/knowledge-base/api-keys.md) for a *test* sales unit: * `client_id` - Client ID for the sales unit. * `client_secret` - Client secret for the sales unit. * `Ocp-Apim-Subscription-Key` - Subscription key for the sales unit. * `merchantSerialNumber` - The unique ID (MSN) for the sales unit. [Partner keys](https://developer.vippsmobilepay.com/docs/partner/partner-keys.md#partner-keys) only work in the production environment. To follow this guide in the test environment, use the test sales unit API keys provided in your welcome email. Login has its own partner key flow, which differs from the merchant flow -- see [Login API: Partner keys](https://developer.vippsmobilepay.com/docs/APIs/login-api/api-guide/partner-keys.md). If you're new to the platform, see [Getting started](https://developer.vippsmobilepay.com/docs/getting-started.md) for information about API keys, product activation, and the test environment. The example values in this guide must be replaced with the values for your sales unit and user. This applies to API keys, HTTP headers, references, phone numbers, and similar values. **Important** Your test sales unit must be set up for using login. See [How to set up login on your sales unit](https://developer.vippsmobilepay.com/docs/knowledge-base/portal.md#how-to-set-up-login-for-your-sales-unit). ### Step 1 - Setup In addition to the keys listed in [Before you begin](#before-you-begin) ([How to find the API keys](https://developer.vippsmobilepay.com/docs/knowledge-base/portal.md#how-to-find-the-api-keys)), you will need: * `internationalMobileNumber` - The MSISDN for the test app profile you have received or registered. This is your test mobile number including country code. * `redirect_uri` - The website to send the user to after they log in. This must be exactly the same redirect URI as the one you specified on your sales unit on the [business portal](https://portal.vippsmobilepay.com). For help, see [Portal: How to set up login on your sales unit](https://developer.vippsmobilepay.com/docs/knowledge-base/portal.md#how-to-set-up-login-for-your-sales-unit). If using Postman, download the following files and import them into Postman. Select the global environment as your active environment and update with your own values for the API keys, `redirect_uri`, and international mobile number. *Don't store production keys in the cloud.* * [Download Login API Postman collection](https://developer.vippsmobilepay.com/tools/login-api.postman_collection.json) * [Download Global Postman environment](https://developer.vippsmobilepay.com/tools/global-postman-environment.json) ### Step 2 - Get OIDC well-known endpoint Get configuration information for OpenID Connect clients by using [OpenID configuration endpoint](https://developer.vippsmobilepay.com/redocusaurus/login-swagger-id.yaml). To learn more about this endpoint, please refer to the [OpenID specification](https://openid.net/specs/openid-connect-discovery-1_0.html). ```bash Send request "Get OIDC well-known" ``` From the response, you can get several values, including the paths of other Login endpoints that you will need later in the flow. These are updated in your environment. This will also create the [Start login URL](#step-3---create-the-start-login-url). ```bash curl -X GET https://apitest.vipps.no/access-management-1.0/access/.well-known/openid-configuration \ -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" \ ``` From the response, you can get several values, including the paths of other Login endpoints that you will need later in the flow: * `authorization_endpoint` - e.g., `https://apitest.vipps.no/access-management-1.0/access/oauth2/auth` - You will use this to build a *start login URL*. * `token_endpoint` - e.g., `https://apitest.vipps.no/access-management-1.0/access/oauth2/token` * `userinfo_endpoint`- e.g., `https://apitest.vipps.no/vipps-userinfo-api/userinfo` * `backchannel_authentication_endpoint` - e.g., `https://apitest.vipps.no/vipps-login-ciba/api/backchannel/authentication` Example response ```json { "issuer": "https://apitest.vipps.no/access-management-1.0/access/", "authorization_endpoint": "https://apitest.vipps.no/access-management-1.0/access/oauth2/auth", "device_authorization_endpoint": "https://apitest.vipps.no/access-management-1.0/access/oauth2/device_authorization", "token_endpoint": "https://apitest.vipps.no/access-management-1.0/access/oauth2/token", "token_endpoint_auth_methods_supported": [ "client_secret_post", "client_secret_basic" ], "jwks_uri": "https://apitest.vipps.no/access-management-1.0/access/.well-known/jwks.json", "userinfo_endpoint": "https://apitest.vipps.no/vipps-userinfo-api/userinfo", "end_session_endpoint": "https://apitest.vipps.no/access-management-1.0/access/not-in-use", "response_types_supported": [ "code", "code id_token", "id_token", "token id_token", "token", "token id_token code" ], "grant_types_supported": [ "authorization_code", "client_credentials" ], "revocation_endpoint": "https://apitest.vipps.no/access-management-1.0/access/oauth2/revoke", "code_challenge_methods_supported": [ "S256" ], "tls_client_certificate_bound_access_tokens": true, "subject_types_supported": [ "public", "pairwise" ], "id_token_signing_alg_values_supported": [ "RS256" ], "scopes_supported": [ "openid", "name", "phoneNumber", "nin", "address", "birthDate", "delegatedConsents", "email", "gender" ], "claims_supported": [ "sub" ], "response_modes_supported": [ "query", "fragment" ], "userinfo_signing_alg_values_supported": [ "none" ], "request_parameter_supported": true, "request_uri_parameter_supported": true, "require_request_uri_registration": true, "claims_parameter_supported": false, "backchannel_logout_supported": false, "backchannel_logout_session_supported": false, "frontchannel_logout_supported": false, "frontchannel_logout_session_supported": false, "request_object_signing_alg_values_supported": [ "none" ], "backchannel_authentication_endpoint": "https://apitest.vipps.no/vipps-login-ciba/api/backchannel/authentication", "backchannel_token_delivery_modes_supported": [ "poll" ] } ``` ### Step 3 - Create the start login URL Create the *Start Login URL*, using the OAuth 2.0 authorize endpoint [`GET:/access-management-1.0/access/oauth2/auth`](https://developer.vippsmobilepay.com/redocusaurus/login-swagger-id.yaml). In Postman, this is created for you automatically by the previous step. ```bash Open your active Postman environment and copy the value of key `start_login_uri`. ``` To build the login URL manually, use the following format: ```bash ?client_id=&response_type=&scope=&state=&redirect_uri= ``` Replace each placeholder with your actual values: * ``: The URL from the `authorization_endpoint` field in the OIDC configuration response. * ``: Your client ID. If you are a **partner**, you should use the **MSN of the target sales** unit instead of your client ID. * ``: Usually `code`. * ``: The [scopes](https://developer.vippsmobilepay.com/docs/APIs/login-api/api-guide/user-info.md#scopes) you want to request, e.g. `openid name phoneNumber address birthDate` (space-separated, URL-encoded as `%20`). * ``: A random string to maintain state between the request and callback (for security, generate a new random value each time). * ``: The redirect URI you registered in the Vipps MobilePay portal. **Example:** ```html https://apitest.vipps.no/access-management-1.0/access/oauth2/auth?client_id=YOUR-CLIENT-ID&response_type=code&scope=openid%20name%20phoneNumber%20address%20birthDate&state=8652682f-ba1d-4719-b1ec-8694ba97bde7&redirect_uri=https://your-redirect-uri.example.com ``` ### Step 4 - Log the user in Log yourself in by pasting the *start login URL* into the address field of any browser. The landing page will open, and you should enter your test phone number. (If you click *Remember me in browser*, then you'll skip this page next time.) Go to your Vipps or MobilePay app to complete the login. Back in the browser, you will see the consent screen with the scopes requested in the URL. Click *Continue*. Then the redirect URL will be opened. ### Step 5 - Get the access token In your browser, on the redirect URL page, copy the `code` value out from the address field in the URL. You will use this to get an access token. ```text 1. In your active Postman environment, paste the code into the `code` field. 2. Send request "Get token" ``` Use the `code` and client credentials in the [`POST:/access-management-1.0/access/oauth2/token`](https://developer.vippsmobilepay.com/redocusaurus/login-swagger-id.yaml) request. The client credentials are represented as a base64-encoded string consisting of the client_id and client_secret issued by Vipps MobilePay. Example in JavaScript: ```javascript const clientId = "123456-test-4a3d-a47c-412136fd0871" const clientSecret = "AAAAAAAAAAAAAAAAAAAAAA==" const combinedString = `${clientId}:${clientSecret}`; const clientCredentials = Buffer.from(combinedString, 'utf8').toString('base64'); ``` ```bash curl -X POST https://apitest.vipps.no/access-management-1.0/access/oauth2/token \ -H 'Content-Type: application/x-www-form-urlencoded' \ -H 'Authorization: Basic {client_credentials}' \ -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-urlencode 'grant_type=authorization_code' \ --data-urlencode 'code=THE CODE FROM THE URL' \ --data-urlencode 'redirect_uri=http://the-exact-redirect-uri-configured-on.portal.vippsmobilepay.com' ``` **NOTE** The [`POST:/access-management-1.0/access/oauth2/token`](https://developer.vippsmobilepay.com/redocusaurus/login-swagger-id.yaml) endpoint uses `Basic` authentication for merchants, and `Bearer` for partners using partner keys. Copy the access token from the response. You will use it for the userinfo request. ### Step 6 - (Optional) Get userinfo Send request [`GET:/vipps-userinfo-api/userinfo/`](https://developer.vippsmobilepay.com/redocusaurus/login-swagger-id.yaml). Use the access token from the previous step. Note, the access token expires after 10 minutes, so if you get an unauthorized message, you should start over at step 2. ```text Send request "Get userinfo" ``` ```bash curl -X GET https://apitest.vipps.no/vipps-userinfo-api/userinfo/ \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR-ACCESS-TOKEN" \ -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" \ ``` You will get a response with the consented scopes. Example response ```json { "address": { "address_type": "home", "country": "NO", "formatted": "BOKS 6300, ETTERSTAD\n0603\nOSLO\nNO", "postal_code": "0603", "region": "OSLO", "street_address": "BOKS 6300, ETTERSTAD" }, "birthdate": "1955-05-18", "family_name": "User", "given_name": "Test", "name": "Test User", "other_addresses": [ { "address_type": "work", "country": "NO", "formatted": "Robert Levins gate 5\n0152\nOslo\nNO", "postal_code": "0152", "region": "Oslo", "street_address": "Robert Levins gate 5" } ], "phone_number": "4748571123", "phone_number_verified": true, "sid": "f2373816-439c-40e4-9882-afe7d79dd170", "sub": "126684df-c056-4625-821d-f2905febe3f9" } ``` ## Next steps Head over to the [Login API guide](https://developer.vippsmobilepay.com/docs/APIs/login-api/api-guide/README.md) to continue your journey with the Login API. > **Full site overview:** For every page in this documentation, read [https://developer.vippsmobilepay.com/llms.txt](https://developer.vippsmobilepay.com/llms.txt).