End user API

This section covers the end user API. It's divided into the following subsections:

• Authentication
• Access Token API
  • Overview of access tokens
  • Delete / revoke access token
• Consent API
  • Overview of consents
  • Delete / revoke consent
• Device API
  • Overview of devices
  • Delete / revoke device
  • Disable finger print
  • Disable mobile authentication
• Applications API
  • Overview of Applications
  • Delete / revoke access to application
• Notification Setting API
  • Lookup value
  • Set notification setting
    • Invalid Notification Type
  • Delete notification setting
• Authentication applications API
  • Overview of Authentication applications
  • Delete authentication application instances

Authentication

Usage of any API using the /api/* uri pattern does require authentication of the API user. The authentication is enforced via HTTP Basic Authentication. The username and password for the API can be configured via the following Docker Compose environment variables:

Encrypting the authentication parameters is highly recommended.

Access Token API

The access token API enables the end user to list the access tokens are used for its resources. The API will also offer the end user the possibility to revoke access for a client to the resources by deleting a specific access token.

Overview of access tokens

Endpoint: GET /oauth/api/v1/users/{userId}/tokens

When no tokens are found because the user does not exist or the user has no valid access tokens a 404 NOT FOUND is returned. When the user does have valid tokens an array with one or more tokens is returned. Each token object has the following attributes:

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "tokens": [
    {
      "id": "7d507b7e-6221-4f06-a75e-ef6e6f06d32b",
      "client_name": "Client X",
      "device_name": "my iPad",
      "created_at": 1381322054000,
      "scopes": [
        "email",
        "profile"
      ],
      "type":"DEFAULT"
    },
    {
      "id": "1c05119e-21b2-4905-bc93-8f67790a16d6",
      "client_name": "Client Y",
      "created_at": 1381321302000,
      "scopes": [
        "email"
      ],
      "type":"FINGER_PRINT"
    }
  ]
 }

Example error response

{
  "error": "No tokens found"
}

Delete / revoke access token

Endpoint: DELETE /oauth/api/v1/users/{userId}/tokens/{tokenId}

Consent API

The consent API enables the end user to list the consents that are given. The API will also offer the end user the possibility to revoke consent for a client by deleting a specific consent entry.

Overview of consents

Endpoint: GET /oauth/api/v1/users/{userId}/consents

When no consents are found because the user does not exist or the user does not have consents, a 404 NOT FOUND will be returned. When the user does have consents an array with one or more consents is returned. Each consent object has the following attributes:

Example result

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "consents": [
    {
      "id": "fc4ef972-7167-4421-aa89-f109be79d7c2",
      "client_name": "Client X",
      "device_name": "My iPad",
      "scopes": [
        "email",
        "profile"
      ]
    },
    {
      "id": "451f5c34-3d03-4ce0-80bd-4676fc0eddf5",
      "client_name": "Client Y",
      "scopes": [
        "email"
      ]
    }
  ]
}

Example error response

{
  "error": "No consents found"
}

Delete / revoke consent

Endpoint: DELETE /oauth/api/v1/users/{userId}/consents/{consentId}

Deleting a consent for a specific user & client will also remove the corresponding Access Grant and Access Token when available.

The API will always return a "HTTP 204 no content" response, independent of the execution result.

Example result

HTTP/1.1 204 No Content
Cache-Control: no-store
Pragma: no-cache

Device API

The device API enables the end user to list the devices that he has (dynamically) registered. The API will also offer the end user the possibility to delete a device.

Overview of devices

Endpoints:

• GET /oauth/api/v1/users/{userId}/devices
• GET /oauth/api/v2/users/{userId}/devices

When no devices are found because the user does not exist or the user does not have any devices, a 404 NOT FOUND will be returned. When the user does have devices an array with one or more devices is returned. Each device object has the following attributes: (in API version 2, new attributes have been added, they are marked as v2 in the Version column)

Example result

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "devices": [
    {
      "id": "fc4ef972-7167-4421-aa89-f109be79d7c2",
      "name": "Device X",
      "application": "application 1",
      "platform": "ANDROID",
      "created at": 1381322054000        
    },
    {
      "id": "451f5c34-3d03-4ce0-80bd-4676fc0eddf5",
      "name": "Device Y",
      "application": "application 2",
      "platform": "IOS"
    }
  ]
}

Example error response

{
  "error": "No devices found"
}

Delete / revoke device

Endpoint:

• DELETE /oauth/api/v1/users/{userId}/devices/{deviceId}
• DELETE /oauth/api/v2/users/{userId}/devices/{deviceId}

The API will always return a "HTTP 204 no content" response, independent of the execution result.

In API version 2, when there are multiple users (profiles) registered on a device, only data related to the provided user_id will be deleted.

Example result

HTTP/1.1 204 No Content
Cache-Control: no-store
Pragma: no-cache

Disable finger print

Endpoint:

• POST /oauth/api/v2/users/{userId}/devices/{deviceId}/disableFingerprint

The API will always return a "HTTP 204 no content" response, independent of the execution result.

Disable mobile authentication

Endpoint:

• POST /oauth/api/v2/users/{userId}/devices/{deviceId}/disableMobileAuthentication

The API will always return a "HTTP 204 no content" response, independent of the execution result.

Applications API

Via this API the user can manage access to his applications. An application can be a web client or a group of dynamic clients that use the same configuration (e.g. the instances that are installed on a tablet and on a mobile phone are separate dynamic clients but refer to the same application).

Overview of Applications

Endpoint: GET /oauth/api/v1/users/{userId}/applications

When no applications are found because the user does not exist or the user does not have any applications, a 404 NOT FOUND will be returned. When the user does have applications an array with one or more applications is returned. Each applications object has the following attributes:

Example result

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "apps": [
    {
      "id": "69cd25e7-ec86-43e2-8714-8fbb1d7583ec",
      "app_name": "Application X"
    },
    {
      "id": "408a9d9a-2b25-4c7a-8e2c-038150ab040c",
      "app_name": "Application Y"
    }
  ]
}

Example error response

{
  "error": "No applications found"
}

Delete / revoke access to application

By deleting access for a user to an application, all access tokens, access grants & consents a user has for any instance of the application will be removed.

Endpoint: DELETE /oauth/api/v1/users/{userId}/applications/{applicationId}

The API will always return a "HTTP 204 no content" response, independent of the execution result.

Notification Setting API

Via this API the notification setting for a user can be looked up, set and deleted. Currently Onegini supports the following notification types: EMAIL, SMS, NONE. In case of EMAIL an email notification is send to the end-user. In case of SMS an sms message is send to the end-user. In case of NONE the user is not notified.

Lookup value

Endpoint: GET /oauth/api/v1/users/{userId}/settings/notification/

When no notification settings is set for a user, but the user does have one or more tokens or consents the default value, EMAIL, will be returned as a result. The notification setting is returned as a Json response containing the notification type. For users which are unknown because there is no notification setting plus tokens and consents are missing a "404 NOT FOUND" response will be returned.

Example result

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "notification_type": "EMAIL"
}

Example error response

{
  "error": "No notification setting found."
}

Set notification setting

Endpoint: POST /oauth/api/v1/users/{userId}/settings/notification/{notificationType}

If the user already has a notification setting set, the old value will be overridden. The API will return a "HTTP 204 no content" response, when the setting was successfully set.

Example result

HTTP/1.1 204 No Content
Cache-Control: no-store
Pragma: no-cache

Invalid Notification Type

If the notification type was unknown an error response will be returned. The response type for the error response is "HTTP 400 bad request".

Example error result

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache


{
  "error" : "INVALID_NOTIFICATION_TYPE"
}

Delete notification setting

Endpoint: DELETE /oauth/api/v1/users/{userId}/settings/notification/

The API will always return a "HTTP 204 no content" response, independent of the execution result.

Example result

HTTP/1.1 204 No Content
Cache-Control: no-store
Pragma: no-cache

Authentication applications API

Via this API the user can manage application instances used for authentication. An application can be a web client or a group of dynamic clients that use the same configuration (e.g. the instances that are installed on a tablet and on a mobile phone are separate dynamic clients but refer to the same application).

Overview of Authentication applications

Endpoint: GET /oauth/api/v1/users/{userId}/authentication/apps

When no applications are found because the user does not exist or the user does not have any authentication applications, a 404 NOT FOUND will be returned. When the user does have authentication applications an array with one or more applications is returned. Each object has the following attributes:

Example result

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "authentication_app_instances": [
    {
      "id": "77cea55b-c82f-448f-b0a1-6cd4c07bdb54",
      "device_id": "fc4ef972-7167-4421-aa89-f109be79d7c2"
      "device_name": "My device",
      "platform": "ANDROID"
    }
  ]
}

Example error response

{
  "error": "No authentication apps found"
}

Delete authentication application instances

By deleting an authentication application instance the application instance can not be used for mobile authentication anymore until enrolled again.

Endpoint: DELETE /oauth/api/v1/users/{userId}/authentication/apps/{applicationInstanceId}