Your suggested change has been received. Thank you.
Your suggested change has been received. Thank you.
Download OpenAPI specification:Download
When your platform makes a request to our API, it does so on behalf of one of your users. To do this securely, you must first obtain an access token for the user and then include that token in every subsequent request by setting the Authorization-header of the HTTP request. Requesting an access token requires the user's ID and password. You don't want to get a new token for every request; instead, you should re-use the token for multiple requests.
However, the access token expires. If this happens, you should refresh it. When you request an access token, you will also get a refresh token. You can exchange this refresh token for a fresh access token (and a new refresh token). This way, your user won't have to re-enter their credentials, even if the access token expires.
When you request an access token, you need to indicate which scopes you want to include in the token. A scope defines which endpoints you can call using the access token. For example, if you want to be able to use the access token for sending push notifications, you'll need to request the scope credential:omi:push-notification:post. You can request multiple scopes for a single access token. In fact, you will need to if you intend to check if your push notification was confirmed by the user, because that requires credential:omi:push-notification:status:get.
You should request one access token for your user with all the required scopes. There's no need to request separate access tokens for each scenario. For example, if you want to use both QR codes and push notifications, you can request a single access token with the scopes credential:omi:enrol:qr:post, credential:omi:enrol:status:get, credential:omi:push-notification:post, and credential:omi:push-notification:status:get. Of course, you shouldn't request scopes you're never going to use, so if you don't intend to use QR codes, don't request the scopes credential:omi:login:qr:post and credential:omi:login:status:get.
Get a QR code that you can display to the user. The user can then scan the QR code using the authenticator app on the device they wish to use for authentication in the future. This is a protected endpoint:
| user_id required | string^[a-zA-Z0-9]{8}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{... The id of the user. |
| format | string Default: "png" Enum: "raw" "png" |
API docs by Redocly{- "user_id": "string",
- "format": "raw"
}{- "qr_code": "string",
- "nonce": "string",
- "validity_period": 0
}This API can be used to verify if the user successfully scanned the QR code. It accepts the nonce attribute in the header, which was initially generated when creating the QR code. To call this API, an access token with the scope 'credential:omi:enrol:status:get' or 'credential:omi:enrol:status:admin:get' is needed. Once the API returns a 200 OK response, it means that the user successfully scanned the QR code. Using the same nonce again for this API will result in a 400 Bad Request, meaning the nonce is not valid anymore. However, the nonce can still be used for sending a push notification, and the notification will be sent to the device that was used to scan the QR code. Main reason of considering the nonce invalid once used, is to protect against enumeration attacks. In case the request completes successfully, a success event is generated, named EnrolOMIUserSuccessEvent. In case of failure, EnrolOMIUserFailedEvent event is generated. In case the Qr code expired, calling this API will result in an event generated, named OMIQRCodeEnrolmentTimeoutEvent.
| X-iWelcome-Nonce required | string <= 36 characters ^[a-zA-Z0-9]{8}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{... The generated nonce when creating a QR code. |
{- "userId": "string",
- "status": "enrolled"
}Push a notification to a user's specific device. This is a protected endpoint: - the user for this API needs to be authenticated using OAuth - regular users must have 'credential:omi:push-notification:device:post' scope; admin users must have the 'credential:omi:push-notification:device:admin:post' scope For regular users, in case the request completes successfully, a success event is generated, named OMIPushDeviceNotificationSuccessEvent. In case of failure, OMIPushDeviceNotificationFailedEvent event is generated. For admin users, in case the request completes successfully, a success event is generated, named OMIAdminPushDeviceNotificationSuccessEvent. In case of failure, OMIAdminPushDeviceNotificationFailedEvent event is generated.
| userId required | string <= 36 characters ^[a-zA-Z0-9]{8}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{... The id of the user |
| deviceId required | string The id of the device |
| X-iWelcome-Nonce required | string <= 36 characters ^[a-zA-Z0-9]{8}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{... Nonce to identify the browser/webserver session. |
Push user notification request
| message required | string Represents the message that will be displayed on the push notification on user’s device. |
{- "message": "string"
}{- "validity_period": 0
}This API can be used to verify if the user successfully confirmed the notification. It accepts the nonce attribute in the header, which was initiated when the push notification was sent. This endpoint is protected with OAuth and regular users must have 'credential:omi:push-notification:status:get' scope and admin users must have 'credential:omi:push-notification:status:admin:get' scope. Once the API returns a 200 OK response, it means that the push notification has been confirmed, and using the same nonce again for subsequent calls to this API will result in a 400 bad request because the nonce will become invalid once used. Main reason of considering the nonce invalid once used, is to protect against enumeration attacks. In case the request completes successfully, a success event is generated, named OMIPushConfirmationSuccessEvent. In case the nonce expired, calling this API will result in an event generated, named OMIPushConfirmationTimeoutEvent.
| X-iWelcome-Nonce required | string <= 36 characters ^[a-zA-Z0-9]{8}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{... The generated nonce when push notification was sent. |
{- "userId": "string",
- "accountId": 0,
- "status": "confirmed"
}This API returns all devices for a specific user, identified by the userId path parameter. In order to allow an authenticated user to get all his/her devices, the access token must have the scope 'credential:omi:devices:get'. This API can also be called by an administrator to return all the devices for a specific user, and in order to be able to do that, the scope 'credential:omi:devices:admin:get' is required. This API also generates two events, one success and one failed event. For regular users, in case the request completes successfully, a success event is generated, named OMIGetDevicesSuccessEvent. In case of failure, OMIGetDevicesFailedEvent event is generated. For admin users, in case the request completes successfully, a success event is generated, named OMIAdminGetDevicesSuccessEvent. In case of failure, OMIAdminGetDevicesFailedEvent event is generated.
| userId required | string <= 36 characters ^[a-zA-Z0-9]{8}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{... The id of the user. |
[- {
- "id": "string",
- "created": 0,
- "lastLogin": 0,
- "metadata": { }
}
]This API deletes all devices of a specific user. The user itself is not deleted. In order to allow an authenticated user to delete all his/her devices, the access token must have the scope 'credential:omi:user:devices:delete'. This API can also be called by an administrator to delete a specific user's devices, and in order to be able to do that, the scope 'credential:omi:user:devices:admin:delete' is required. For regular users, in case the request completes successfully, a success event is generated, named OMIDeleteUserDevicesSuccessEvent. In case of failure, OMIDeleteUserDevicesFailedEvent event is generated. For admin users, in case the request completes successfully, a success event is generated, named OMIAdminDeleteUserDevicesSuccessEvent. In case of failure, OMIAdminDeleteUserDevicesFailedEvent event is generated.
| userId required | string <= 36 characters ^[a-zA-Z0-9]{8}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{... The id of the user. |
This API deletes a specific device. This is a protected endpoint: - the user for this API needs to be authenticated using OAuth - regular users must have the 'credential:omi:device:delete' scope; admin users must have the 'credential:omi:device:admin:delete' scope For regular users, in case the request completes successfully, a success event is generated, named OMIDeleteDeviceSuccessEvent. In case of failure, OMIDeleteDeviceFailedEvent event is generated. For admin users, in case the request completes successfully, a success event is generated, named OMIAdminDeleteDeviceSuccessEvent. In case of failure, OMIAdminDeleteDeviceFailedEvent event is generated.
| userId required | string <= 36 characters ^[a-zA-Z0-9]{8}-?[a-zA-Z0-9]{4}-?[a-zA-Z0-9]{... The id of the user |
| deviceId required | string Identifier of the device |