# 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 (opens new window)
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 (opens new window)
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 (opens new window)
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. https://ssp.settle.eu/oauth/auth (opens new window) (or similar)
- Authorization server redirects user back to client redirect_uri, with authorization code
- Client exchanges authorization code for access token (https://ssp.settle.eu/oauth/token (opens new window)) using client credentials
- Client accesses protected resource with access token
# Settle API permission request (opens new window)
In the Settle API, there is an endpoint for requesting authorization
POST /permission_request/ (opens new window), a direct callback with the access token, and an outcome endpoint
GET /permission_request/<rid>/outcome/ (opens new window) 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 (opens new window)
The access token can be used in the
customer field when making payment requests at
POST /payment_request/ (opens new window).
# Scope values (opens new window)
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: http://openid.net/specs/openid-connect-basic-1_0-28.html#scopes (opens new window)
To make a OpenID Connect request for login. NOTE: the
openidscope is also required in order to access the
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. http://openid.net/specs/openid-connect-basic-1_0-28.html#scopes (opens new window)
shipping_address, and specific personal id schemes like bankid, the endpoint URI is a little different.
verified fodselsnummer for user, listing proofs for jurisdiction
verified fodselsnummer from
BankID, single entry in proof list
# OpenID ID token (opens new window)
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) (opens new window).