About the HID Authentication Service SCIM API
The HID Authentication Service SCIM API exposes the user and group management RESTful endpoints added to the HID Authentication Service server that comply with standard SCIM protocols. It also includes proprietary extensions to manage objects such as devices and credentials.
The API objects and endpoints are described in the OpenAPI Connect Core specification (JSON file) that you can use to discover the SCIM API.
This site provides the specification for the API to help integrators access HID Authentication Service functionality through the SCIM RESTful API endpoints.
The API reference content is designed to help developers understand:
- Resource endpoints
- CRUD (HTTPS methods) operation on resources
- Request and Response payloads
- Content-type
application/json; charset=UTF-8andapplication/x-www-form-urlencoded - Error codes
To use the version-specific parameters/attributes, you must add api-version=N to the query parameter.
Previous versions of the API are also supported with the corresponding functionality.
Base URI
-
All URLs referenced in HID Authentication Service SCIM API Endpoints begin with the following base URL:
https://[base-server-url]/scim/{tenant}
-
All URLs referenced in HID Authentication Service SCIM Configuration API Endpoints begin with the following base URL:
https://[base-server-url]/configuration/{tenant}
-
All references to
[base-server-url]are a placeholder to be replaced with
-
All references to
{tenant}are a placeholder to be replaced with -
For the following endpoints that require authentication via Bearer Token on HTTP Header, the Bearer token must be generated using HID Authentication Service OAuth/OpenID Connect REST API
Date Format
Four date formats are supported (conforming to ISO 8601 as defined in RFC7159 - section 7):
-
yyyy-MM-dd'T'HH:mm:ssXX
-
yyyy-MM-dd'T'HH:mm:ssXXX
-
yyyy-MM-dd'T'HH:mm:ss.SSSXX
-
yyyy-MM-dd'T'HH:mm:ss.SSSXXX
For example, these three dates are supported:
-
2017-06-04T10:15:30Z
-
2017-06-04T12:15:30+0200
-
2017-06-04T12:15:30.000+02:00
Standards
The API uses a standards-based approach to facilitate integration. The supported standards are:
| SCIM |
[SCIM-DEFINITIONS] - https://tools.ietf.org/html/rfc7642 [SCIM-CORE] – https://tools.ietf.org/html/rfc7643 [SCIM-PROTOCOL] - https://tools.ietf.org/html/rfc7644 |
|---|---|
| Date Format |
ISO8601 formatted JSON String as per Section 7 [RFC7159. |
Glossary of Terms
| Term | Description |
|---|---|
| ACR |
Authentication Context Class Reference The set of rules required by a provider or relying party that define how a user authenticates to mitigate specific authentication risks using a specific, or combination of, authentication methods. These rules correspond to the Authenticator Assurance Levels defined in the NIST standard (where 1 is the weakest, and 3 the strongest). |
|
ALSI |
Authenticated Login Session Identifier |
|
CIBA |
Client Initiated Backchannel Authentication See the OpenID CIBA specification for more details. |
|
Endpoint |
An endpoint is a defined base path relative to the HID Authentication Service base URL over which API operations may be performed against protected resources. |
|
JSON |
JavaScript Object Notation Open standard format that uses lightweight text to store and transport data objects consisting of attribute/value pairs. Used primarily to transmit data between a server and web application, as an alternative to XML See the JSON RFC7159 specification for more details. |
|
JWA |
JSON Web Algorithms See the JWA RFC7518 specification for more details. |
|
JWE |
JSON Web Encryption See the JWE RFC7516 specification for more details. |
|
JWK |
JSON Web Key See the JWK RFC7517 specification for more details. |
|
JWKS |
JSON Web Key Set Signed (RSA or ECDSA algorithms) set of public keys used to verify a JSON Web Key (JWT) issued by an authorization server. |
|
JWS |
JSON Web Signature See the JWS RFC7515 specification for more details. |
|
JWT |
JSON Web Token See the JWT RFC7519 specification for more details. |
|
OAuth2 |
Authorization delegation standard (see Standards for more details). |
|
OIDC |
OpenID Connect (see Standards for more details) |
|
OpenID Client |
An OpenID client represents a client application of the HID Authentication Service. This allows an application to leverage the HID Authentication Service APIs, and for the authentication server to authenticate the client application. It is setup in HID Authentication Service as a user with valid credentials and permission set. |
|
PALSI |
Proxy Authenticated Login Session Identifier . |
|
PKCE |
Proof Key for Code Exchange See the PKCE RFC7636 specification for more details. |
|
REST |
Representational State Transfer Architectural style used to perform CRUD operations over the web using HTTP methods such as GET, POST, PUT, DELETE |
|
SCIM |
System for Cross-domain Identity Management It is an application-level HTTPS-based protocol with predefined schema for provisioning and managing identity data across domains. The protocol supports creation, modification, retrieval and discovery of core identity resources such as Users and Groups, as well as custom resources and resource extensions. See the SCIM protocol specifications for more details. |
|
Tenant |
In the endpoint, {tenant} is the placeholder for the HID Authentication Service security domain. |
|
Token |
A token contains information about the user, their privileges, their group and roles, the authenticator used for the authentication. A token allows you to "prove" that a user is authenticated against HID Authentication Service. A token has a lifetime and thus expires. It is comparable to the principle of web sessions. The token is thus a proof of an identity as well as a credential to access the HID Authentication Service APIs. HID Authentication Service supports different types of tokens:
|
