API Endpoints

Since ClearID is a microservice architecture, it's not one single API endpoint that contains all the different possible REST API.

Different type of functionalities have different API Endpoints; creating a new Identity/Cardholder isn't the same API endpoint that create a location under a site.

Behind the scene, it's probably not even the same machine that will process the API call.

ClearID Endpoints

Description

API Details

Secure Token Service (STS)

The service is responsible to authenticate computers and return the Token required to call any other ClearID API endpoints.

It's a standard OAuth endpoint.

Dev environment:
https://sts-demo.clearid.io

Production:
https://sts.clearid.io

Identity Service

An Identity represents usually an employees or a contractor that has an access Control card.

  • Create Identities in the system
  • Update Identities
  • Get Identity using your own ID or ClearID ID

Dev environment:
https://identityservice-demo.clearid.io/swagger/

Production:
https://identityservice.clearid.io/swagger/

Search Service

Search service can allow users to search different type of entities in the system based on different criteria.

  • Identities
  • Locations
  • Sites
  • Teams/Roles
  • Visit Events
  • Visit Requests
  • Access Requests

Dev environment:
https://searchservice-demo.clearid.io/swagger/

Production:
https://searchservice.clearid.io/swagger/

Location Service

A location represents a physical area where you want to grant access to someone (identity) or a group of people(Role) for a certain period of time or permanently.

  • Create or update locations
  • Grant or Deny access to Identities or Role to a location

Dev environment:
https://locationservice-demo.clearid.io/swagger/

Production:
https://locationservice.clearid.io/swagger/

Site Service

A site represent a building or a campus that is composed of one or multiple locations.

A Site is link to an address and one Security Center system that manage the access for that site.

Dev environment:
https://siteservice-demo.clearid.io/swagger/index.html

Production:
https://siteservice.clearid.io/swagger/

Role Service

A role/team represent people sharing access to the same locations in the system. A Role is represented as a cardholder group is Synergis.

  • Create or Update Roles
  • Add or Remove Identities to the role.
  • Change role owners

Dev environment:
https://roleservice-demo.clearid.io/swagger/

Production:
https://roleservice.clearid.io/swagger/

Visit Request Service

A visit request must be created to invite visitors on a site.

It specifies the list of guest, host, date&Time, sites, location.

This endpoint is designed to invite visitors on a site.

Dev environment:
https://vrservice-demo.clearid.io/swagger/

Production:
https://vrservice.clearid.io/swagger/index.html

Role Provisioning Policy Service

A provisioning policy manages the identities that are part of a role based on the identities' attributes.

Dev environment:
https://rps-demo.clearid.io/swagger/

Production:
https://rps.clearid.io/swagger/

Principal Service

The principals allows the authentication to the ClearID API endpoints

Dev environment:
https://principalservice-demo.clearid.io/swagger/

Production:
https://principalservice.clearid.io/swagger/

📘

Account ID in all API calls

Account ID is always a mandatory parameter
An important concept to understand is the fact that ClearID is a multi-tenant service. Each time an API request, you must specify on which ClearID account you are attempting the request and the system will very that you have the permission on this account.

In every API call you will see the accountId as a required parameter. This account ID is immutable and be identified in the URI of the web interface

https://demo.clearid.io/abc12exd/... -> The account ID is: abc12exd
https://portal.clearid.io/yxwemsoer/.... -> The account ID is: yxwemsoer

🚧

Read base API URL from the JSON configuration file

As a good practice, you should put the the base URL of the API endpoints you are using in a configuration file instead of directly in the code to avoid having to recompile the code once you move from a development to a production account.