General information#

REST API versions#

Currently, the following versions of the REST API are available in Blitz Identity Provider, which differ in the authorization method:

Warning

Services of versions v1 and v2 after the appearance of analogues in the newer v3 will be marked as obsolete, and it will be recommended to switch from their use to services v3.

  • v1 – REST services available at the following addresses:

    • https://login.company.com/blitz/reg/api/v1/,

    • https://login.company.com/blitz/api/v1/.

    HTTP Basic authorization is used to authorize calls to these services. For an application that will call REST services, you must set a password in the application settings on the REST tab of the application protocol settings. All v1 REST services will be available to the application.

    Tip

    If you do not plan to use any of the services, disable their call through the web server settings (nginx).

  • v2 – REST services available at https://login.company.com/blitz/api/v2/. HTTP Basic authorization is used to authorize calls to most of these services, and OAuth 2.0 is used for some services.

  • v3 – REST services available at https://login.company.com/blitz/api/v3/. Oath 2.0 and security tokens received from Blitz Identity Provider are used to authorize calls to these services. Applications` access to various REST services is regulated through permissions (scope).

REST API access modes#

Provided by Blitz Identity Provider services https://login.company.com/blitz/api/v3/ can be called in two modes:

  • user mode,

  • system mode.

User access mode#

In user mode, the service is called with rights in relation to the account of the currently authorized user. When calling the service, the following headers must be passed:

  • Authorization: Bearer <access token with user permissions> – authorization header containing an access token with permissions of the of the current user.

  • X-Forwarded-For: <user IP address> is the header in which the value of the user’s IP address should be transmitted. This value will be recorded in the security event Blitz Identity Provider.

  • User-Agent: <User-Agent value> is the header in which the value User-Agent of the user’s device should be passed. This value will be recorded in the Blitz Identity Provider security event.

Attention

For the user permissions blitz_api_user and blitz_api_user_chg, set the attributes via the general OAuth 2.0 settings.

Possible user permissions

Changing the password

blitz_change_password

To use the POST /blitz/api/v2/users/{subjectId}/password service.

Creating new rights

To use the services:

  • PUT /blitz/admin/api/v3/rights/right7,

  • GET /blitz/admin/api/v3/rights/right7,

  • DELETE /blitz/admin/api/v3/rights/right6.

Account rights management

blitz_user_rights

To use the services:

  • GET /blitz/api/v3/rights/of/{subjectId},

  • POST /blitz/api/v2/users/rights/change.

Getting attributes

blitz_api_user

To use the GET /blitz/api/v3/users/{subjectId} service.

Changing attributes

blitz_api_user_chg

To use the POST /blitz/api/v3/users/{instanceId} service.

Getting two-factor authentication settings, permissions, security question

blitz_api_usec

To use the services:

  • GET /blitz/api/v3/users/{subjectId}/auth,

  • GET /blitz/api/v3/users/{subjectId}/totps,

  • GET /blitz/api/v3/users/{subjectId}/acls,

  • GET /blitz/api/v3/users/{subjectId}/secQsn,

  • POST /blitz/api/v3/users/{subjectId}/secQsn /check.

Changing the password, resetting sessions, changing the security question, two-factor authentication settings, revoking permissions

blitz_api_usec_chg

To use the services:

  • POST /blitz/api/v3/users/{instanceId}/pswd,

  • POST /blitz/api/v3/users/{instanceId}/sessions/reset,

  • POST /blitz/api/v3/users/{instanceId}/secQsn,

  • POST /blitz/api/v3/users/{subjectId}/auth,

  • GET /blitz/api/v3/users/{subjectId}/totps /attach/qr,

  • POST /blitz/api/v3/users/{subjectId /totps /attach/qr,

  • DELETE /blitz/api/v3/users/{subjectId} /secQsn,

  • DELETE /blitz/api/v3/users/{subjectId} /totps/{id},

  • DELETE /blitz/api/v3/users/{subjectId} /acls/{id}.

Getting memorized devices

blitz_api_uapps

To use the GET /blitz/api/v3/users/{subjectId}/apps service.

Deleting memorized devices

blitz_api_uapps_chg

To use the DELETE /blitz/api/v3/users/{subjectId}/apps/{id} service.

Getting security events

blitz_api_uaud

To use the GET /blitz/api/v3/users/{subjectId}/audit service.

Getting a list of external provider accounts

blitz_api_ufa

To use the GET /blitz/api/v3/users/{subjectId}/fa service.

Changing the list of external provider accounts

blitz_api_ufa_chg

To use the services:

  • POST /blitz/api/v3/users/{subject Id}/fa/{fpType}/{fpName}/{sid},

  • DELETE /blitz/api/v3/users/{subjectId}/fa/{fpType}/{fpName}/{sid}.

Login using a QR code

blitz_qr_auth

To use the services:

  • GET /blitz/api/v3/auth/qr/{QR_code},

  • POST /blitz/api/v3/auth/qr/{QR_code}/confirm,

  • POST /blitz/api/v3/auth/qr/{QR_code}/refuse.

The application receives an access token for user permissions at the time of user identification and authentication.

Note

The identification and authentication mechanisms are described in the sections:

System access mode#

This section provides a list of permissions that an application can get to access the REST API.

Attention

For the system permissions blitz_api_user and blitz_api_user_chg, set the attributes via the general OAuth 2.0 settings.

Possible system permissions (permissions granted to the application)

Access to services for working with organizations

blitz_groups

To use the services:

  • GET /blitz/api/v2/grps/{id},

  • POST /blitz/api/v2/grps,

  • POST /blitz/api/v2/grps/{id}?profile={profile},

  • DELETE /blitz/api/v2/grps/{id}?profile={profile},

  • GET /blitz/api/v2/grps/{id}/members,

  • POST /blitz/api/v2/grps/{id}/members/add?profile={profile},

  • POST /blitz/api/v2/grps/{id}/members/rm?profile={profile}.

Assigning and revoking access rights

blitz_rights_full_access

To use the services:

  • PUT /blitz/api/v3/rights,

  • DELETE /blitz/api/v3/rights,

  • GET /blitz/api/v3/rights/on,

  • GET /blitz/api/v3/rights/of.

Revocation of access rights for slave accounts

blitz_rm_rights

To use the POST /blitz/api/v2/users/rights/change service.

Getting attributes of any user

blitz_api_sys_users

To use the GET /blitz/api/v3/users/{subjectId} service.

Changing attributes of any user

blitz_api_sys_users_chg

To use the POST /blitz/api/v3/users/{instanceId} service.

Registration of user account

blitz_api_sys_users_reg

To use the PUT /blitz/api/v3/users service.

Getting two-factor authentication settings, permissions of any user, security question

blitz_api_sys_usec

To use the services:

  • GET /blitz/api/v3/users/{subjectId}/auth,

  • GET /blitz/api/v3/users/{subjectId}/totps,

  • GET /blitz/api/v3/users/{subjectId}/acls,

  • GET /blitz/api/v3/users/{subjectId}/state,

  • GET /blitz/api/v3/users/{subjectId}/secQsn,

  • POST /blitz/api/v3/users/{subjectId}/secQsn/check.

Changing the password, two-factor authentication settings and security question, resetting sessions, revoking permissions of any user

blitz_api_sys_usec_chg

To use the services:

  • POST /blitz/api/v3/users/{instanceId}/pswd,

  • POST /blitz/api/v3/users/{instanceId}/sessions/reset,

  • POST /blitz/api/v3/users/{subjectId}/auth,

  • POST /blitz/api/v3/users/{subjectId}/state,

  • GET /blitz/api/v3/users/{subjectId}/totps/attach/qr,

  • POST /blitz/api/v3/users/{subjectId}/totps/attach/qr,

  • POST /blitz/api/v3/users/{subjectId}/secQsn,

  • DELETE /blitz/api/v3/users/{subjectId}/totps/{id},

  • DELETE /blitz/api/v3/users/{subjectId}/acls/{id},

  • DELETE /blitz/api/v3/users/{subjectId}/secQsn.

Getting any user’s devices

blitz_api_sys_uapps

To use the service:

GET /blitz/api/v3/users/{subjectId}/apps.

Deleting any user’s devices

blitz_api_sys_uapps_chg

To use the service:

DELETE /blitz/api/v3/users/{subjectId}/apps/{id}.

Getting security events for any user

blitz_api_sys_uaud

To use the service:

GET /blitz/api/v3/users/{subjectId}/audit.

Getting a list of external provider accounts

blitz_api_sys_ufa

To use the service:

POST /blitz/api/v3/users/{subjectId}/fa/{fpType}/{fpName}/{sid}.

Changing the list of external provider accounts

blitz_api_sys_ufa_chg

To use the service:

DELETE /blitz/api/v3/users/{subjectId}/fa/{fpType}/{fpName}/{sid}.

Obtaining an access token issued by any external identity provider

fed_tkn_any

You can configure Blitz Identity Provider to store user access tokens issued by external identity providers. This permission allows you to retrieve a stored access token issued by any provider.

To use the service:

GET /blitz/api/v3/users/${subjectId}/fedToken/${fedPointType}/${fedPointName}.

Obtaining an access token issued by a specific external provider

fed_tkn_${fedPointType}_${fedPointName}

You can configure Blitz Identity Provider to store user access tokens issued by external identity providers. This permission allows you to retrieve a stored access token issued by a provider with the ${fedPointType} type and ${fedPointName} name.

To use the service:

GET /blitz/api/v3/users/${subjectId}/fedToken/${fedPointType}/${fedPointName}.

To get an access token for system permission, the application must make a request to get a token:

  • Request POST https://login.company.com/blitz/oauth/te.

  • The request must contain the header Authorization with the value``Basic {secret}``, where secret is client_id:client_secret (for example, app:topsecret) in Base64 format.

  • The request body must contain the following parameters:

    • grant_type – takes the value client_credentials;

    • scope is the requested system permission.

  • In response, the application will receive an access token access_token, its lifetime expires_in and the token type token_type.

    Tip

    It is recommended that the application caches the received access token for repeated use for a time slightly less than the expires_in parameter, after which it receives a new access token for updating in the cache.

  • Possible errors when calling /oauth/te match RFC 6749 and are described here.

Examples

Authorization: Basic YWlzOm…XQ=

POST blitz/oauth/te HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic ZG5ld…lg

grant_type=client_credentials&scope=blitz_groups

{
   "access_token":"QFiJ9mPgERPuusd36mQvD4mfzYolH_CmuddAJ3YKTOI",
   "expires_in":3600,
   "scope":"blitz_groups",
   "token_type":"Bearer"
}

When trying to call a REST service with an expired access token to it: HTTP 401 Unauthorized.