Authentication

Requirements

Existing account

1. API keys

It is recommended to create an API key for your integrations since it simplifies the authentication process.

An API key is a type of token that has a long lifespan and can be used to access endpoints without requiring repeated login attempts.

By creating an API key, you can simplify the authentication process for your application or service, as it can be used instead of a classic token. This can be especially useful in scenarios where multiple requests need to be made to an API and requiring repeated logins for each request would be cumbersome and inefficient.

Additionally, because API keys have a longer lifespan than other types of tokens, they can be more convenient to use and manage.

You can create a Circularo API key with this guide.

2. Authenticate with credentials

HTTP request: POST /login

Description:
Authenticates user using name and password. Retrieves the authentication token to be used for other endpoints that require authentication.

If cookies are enabled, cookie will be automatically set and token will not be required future requests.

Example

Request payload

JS

{
  "name": "judy.corbett@circularo.com",
  "password": "secretPassword"
}

Response

JS

{
  "logged": true,
  "hasPassword": true,
  "isUnlocked": true,
  "token": "ADFFQBYXP2NVGR6PAP3KOR27FETP6",
  "tenant": "default",
  "rights": [ … ],
  "settings": { … },
  "user": { … }
}

Response contains basic information about logged-in user and login properties.

Please note the Authentication token: ADFFQBYXP2NVGR6PAP3KOR27FETP6. It is use to authorize in requests that requires authentication /some_endpoint?token={AUTHENTICATION_TOKEN}
Also note the imageId in signature object. It is needed for signing documents.

JS

{
  // Other response properties
  "user": {
    "config": {
      "signature": [
        {
          "imageId": "ku2xt8i0yx54irpxl0313vxsu0ltq18kccvsl1w2pu220mtx6cxsz63nyhm4r8h7",
          "name": "default"
        }
      ]
    }
  }
}

Do not create a new authentication token for each individual request or sequence of requests! You should use one token for the entire session. Otherwise, you unnecessarily overload our API servers.

3. Oauth

Other option how to authenticate to Circularo are through Oauth providers:

Microsoft
Google
Dropbox
LinkedIn