Getting Started with the ActivID Appliance SCIM API

The ActivID Appliance SCIM API exposes the user and group management RESTful endpoints added to the ActivID Appliance 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. The ActivID-SCIM-OpenAPI.json is available in SDK\Documentation\RESTful_API\

This site provides the specification for the API to help integrators access ActivID Appliance functionality through the SCIM RESTful API endpoints.

The 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-8 and application/x-www-form-urlencoded
• Error codes

Base URI

• All URLs referenced in ActivID Appliance SCIM API Endpoints begin with the following base URL:

  https://[base-server-url]/scim/{tenant}

• All URLs referenced in ActivID Appliance 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 <your-server-host>:<port>

• All references to {tenant} are a placeholder to be replaced with the target security domain name

• For the following endpoints that require authentication via Bearer Token on HTTP Header, the Bearer token must be generated using ActivID Appliance 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
ALSI	Authenticated Login Session Identifier (see Authentication Sessions)
CIBA	Client Initiated Backchannel Authentication See the OpenID CIBA specification for more details.
Endpoint	An endpoint is a defined base path relative to the ActivID Appliance 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. See ActivID Appliance Public Server JWK Set .
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 tActivID Appliance. This allows an application to leverage the ActivID Appliance APIs, and for the authentication server to authenticate the client application. It is setup in ActivID Appliance as a user with valid credentials and permission set.
PALSI	Proxy Authenticated Login Session Identifier (see Authentication Sessions).
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 ActivID Appliance 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 ActivID Appliance. 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 ActivID Appliance APIs. ActivID Appliance supports different types of tokens: Access tokens are the most common way to prove an identity, as well as the easiest to use. You can see it as a session identifier. It does not contain any human-readable data. However, you can use it with any of the ActivID Appliance API endpoints to be granted access to it (depending of course on the roles of your user). Access tokens are part of the OAuth2 specification - section 1.4. ID Tokens are always a JWT (JSON Web Token) and comparable to an access token, but holds JSON readable information about the user and the client. It is also signed, which allows you to validate the identity of the owner as well as the Identity Provider (ActivID Appliance). It is a base64URL-encoded JSON formatted piece of data split into three parts - the header, the body and the signature. It is described in the OpenID Core specification. Refresh Tokens can be obtained while getting an access token (in the same request). It is a specific token that allows your application to fetch a new access token (upon expiration of the previous one) without prompting the end user for their credentials. You can thus "refresh" your access token. Refresh tokens are part of the OAuth2 specification - section 6.