Permission requests and OAuth

A user can authorize a merchant to access various endpoints, typically shipping address or phone number. To enable this in the general case, we use OAuth 2.0. The Settle API also has methods to support this.

OAuth terms and Settle

The end user or customer is the resource owner, as the resource is typically user data or endpoints for doing something on the users behalf. The authorization server is Settle, who is responsible for checking credentials and handing out tokens after the resource owner authorizes access. The Merchant is the client, who consumes the resource.

Application registration

The Merchant is implicitly a confidential OAuth client for the purposes of Settle API calls, with their Settle merchant_id as the client id. There is no need to register redirect URLs for Settle API usage as the Merchant makes all the calls directly.

If the Merchant desires to use standard OAuth with redirects, it must register an application in Settle API or in self service portal. This is equivalent to registering a client in OAuth language. This returns a client id and client secret. Those values can be used to set up standard OAuth client libraries, as they are separate from the regular merchant id and authentication.

OAuth authorization code grant

When we use regular OAuth, the authorization code grant flow is the default:

  • Client redirects user to authorization server endpoint, where user identifies and approves authorization. (or similar)
  • Authorization server redirects user back to client redirect_uri, with authorization code
  • Client exchanges authorization code for access token ( using client credentials
  • Client accesses protected resource with access token

Settle API permission request

In the Settle API, there is an endpoint for requesting authorization POST /permission_request/, a direct callback with the access token, and an outcome endpoint GET /permission_request/<rid>/outcome/ for checking the outcome later. As the resource owner does not have to carry tokens, there is no checking of redirect_uri and we don't need the authorization code.

Making payment requests

The access token can be used in the customer field when making payment requests at POST /payment_request/.

Scope values

If not requesting any scopes, the result is an access token that can be used as customer field for a payment request or a permission request. For more info on scopes, check out the specification for the protocol:

To make a OpenID Connect request for login. NOTE: the openid scope is also required in order to access the address, phone, and email scopes, in line with the OAuth2 spec.
Included in GET /oauth2/v1/userinfo
Included in GET /oauth2/v1/userinfo
Included in GET /oauth2/v1/userinfo
Included in GET /oauth2/v1/userinfo. Currently this corresponds the claims ['name']. More may be added in the future. See the specification for the openid protocol for more info on this scope.

For Norwegian fodselsnummer, shipping_address, and specific personal id schemes like bankid, the endpoint URI is a little different.

GET /oauth2/v1/scope/shipping_address
verified fodselsnummer for user, listing proofs for jurisdiction
GET /oauth2/v1/scope/personal_id/no/id
verified fodselsnummer from BankID, single entry in proof list
GET /oauth2/v1/scope/personal_id/no/bankid

OpenID ID token

When using OpenID connect scopes, an id token is returned alongside the access token.

An ID Token is a cryptographically-signed JSON object encoded in base 64, represented as a JSON Web Token (JWT).