Skip to content

REST Scope Verification Service API specification

This section describes the API that OneWelcome Access expects when the REST Scope Verification Service is used.

See the topic guide about Scope Verification Service for instructions on enabling this REST service.

The Scope Verification Service endpoint accepts POST requests with application/json or application/json;charset=UTF-8 as the content-type header. Optionally it can be protected with basic authentication. The request body is a json object containing the following properties:

Property Example Description
user_id onegini-user-1234 Unique identifier of the user
external_identity external-identity-abcd Identifier of the user as issued by the identity provider during authentication
scopes [{"id": "read", "service_endpoint": ""}] An array containing scopes to be verified

The endpoint is expected to return 200 OK status code along with json object with the following properties:

Property Example Description
verification_result SUCCESS possible values are SUCCESS or FAILURE
unauthorized_scope read only present when value of verification_result is FAILURE, contains scope for which verification failed

Example request

POST /verify-scope  HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

  "user_id": "onegini-user-1234",
  "external_identity": "external-identity-abcd",
  "scopes": [
      {"id": "read", "service_endpoint": ""}, 
      {"id": "write", "service_endpoint": ""}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

  "verification_result": "FAILURE",
  "unauthorized_scope": "read"