API endpoints are locations where an API stores resources and receives requests for those resources on its servers. Knowing the various Genetec ClearID™ API endpoints allows you to access the resources you need for different functionalities.
Because ClearID is built on a microservice architecture, it does not have a single API endpoint that contains all the various REST APIs.
Different types of functionalities have different API Endpoints. For example, creating a new Identity or Cardholder is not the same API endpoint as creating a location under a site or creating a visit.
Also, because we have multiple load-balanced instances for each endpoint, it is likely that different machines are responsible for handling requests for a specific API endpoint.
Secure Token Service (STS)
| ClearID Endpoints | Description | API details |
|---|---|---|
| Secure Token Service (STS) | The service is responsible for authenticating computers and returning the Token required to call any other ClearID API endpoints. It is a standard OAuth endpoint. | See Authenticating with client secret Dev environment: https://sts-demo.clearid.io/ Production Global: https://sts.clearid.io Production Europe: https://sts.eu.clearid.io/ |
| Identity Service | An Identity usually represents an employee 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 Global: https://identityservice.clearid.io/swagger/ Production Europe: https://identityservice.eu.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 Global: https://searchservice.clearid.io/swagger/ Production Europe: https://searchservice.eu.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 Global: https://locationservice.clearid.io/swagger/ Production Europe: https://locationservice.eu.clearid.io/swagger/ |
| Site Service | A site represents a building or a campus that is composed of one or multiple locations. A site is linked to an address and one Security Center system that manages the access for that site. | Dev environment: https://siteservice-demo.clearid.io/swagger/index.html Production Global: https://siteservice.clearid.io/swagger/ Production Europe: https://siteservice.eu.clearid.io/swagger/ |
| Role Service | A Team/Role represents people sharing access to the same locations in the system. A Role is represented as a cardholder group in Synergis™. Create or Update roles. Add or Remove Identities to the role. Change role owners. | Dev environment: https://roleservice-demo.clearid.io/swagger/ Production Global: https://roleservice.clearid.io/swagger/ Production Europe: https://roleservice.eu.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 Global: https://vrservice.clearid.io/swagger/index.html Production Europe: https://vrservice.eu.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 Global: https://rps.clearid.io/swagger/ Production Europe: https://rps.eu.clearid.io/swagger/ |
| Principal Service | The principals allows the authentication to the ClearID API endpoints. | Dev environment: https://principalservice-demo.clearid.io/swagger/ Production Global: https://principalservice.clearid.io/swagger/Production Europe: https://principalservice.eu.clearid.io/swagger/ |
| System Service | Manage systems connected to your ClearID account. | Dev environment: https://systemservice-demo.clearid.io/swagger/index.html Production Global: https://systemservice.clearid.io/swagger/index.htmlProduction Europe: https://systemservice.eu.clearid.io/swagger/index.html |
Account ID in all API calls
Account ID is always a mandatory parameter.
It is important to understand that ClearID is a multi-tenant service. Each time there is an API request, you must specify on which ClearID account you are attempting the request. The system then verifies that you have the permission on this account.
In every API call, you see the accountId as a required parameter. This account ID is immutable and can 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 base URL of the API endpoints you are using in a configuration file instead of directly in the code. That way, you can avoid having to recompile the code once you move from a development to a production account.