Authentication

Verdigris APIs utilize bearer authentication scheme containing OAuth 2.0 Access Token. Failure to specify this header with a valid token will result in HTTP 401 error from the API server.

OAuth 2.0 Client Credentials Flow

Before you can make authorized requests to Verdigris API, you must first authenticate with the Authorization Server at auth.verdigris.co. The Authorization Server implements an industry standard OAuth 2.0 Client Credentials Flow (as defined in OAuth 2.0 RFC 6748, §4.4: Client Credentials Grant), in which you can pass in Client ID and Client Secret to receive an Access Token.

❗️

Client Secret is sensitive information

The Client Secret must be treated like a password and stored securely. Anyone that has access to your Client ID and Client Secret will be able to generate Access Tokens in all perpetuity to make authorized requests to your building data. For this reason, the Admin Console only shows the Client Secret when the client is generated for the first time.

Access Token

The Access Token returned by the Authorization Server token endpoint (https://auth.verdigris.co/oauth/token) is in the form of a signed JSON Web Token (JWT) with a lifetime of 1 hour. The client does NOT need to make a prior request to retrieve an Access Token every time it needs to make a request to the API.

Rate limits

In order to ensure the quality of service for all customers, the Authorization Server enforces a rate limit on the number of times the client can request an access token per hour.

Requesting the Access Token is restricted to 20 requests per hour (for a maximum of 480 requests per 24 hour period) on a rolling basis. Exceeding these values will trigger an HTTP 429 Too Many Requests error response code. However, expired tokens no longer count towards the rate limit.

📖

Example

If you authenticated 10 times and received 10 tokens at 08:00, you can authenticate 10 more times until 09:00.

If however, you authenticated 5 times at 07:45, and authenticated 15 more times at 08:00, you can still authenticate 5 more times after 08:45 since the first 5 tokens will have expired after an hour.

If your client triggers the rate limit, please refrain from making additional requests until the appropriate amount of time has elapsed.

If you are using massively parallel jobs to retrieve data from our API, please contact our sales team to purchase additional quota.

📘

Tip

Remember to cache your Access Tokens and reuse them! This delays your client from hitting the rate limits and results in better performance since your client does not have to authenticate with the Authorization Server every time it needs to make authorized requests to the API.

How to authenticate

1. The application authenticates with the Verdigris Authorization Server using its Client ID and Client Secret (/oauth/token endpoint).

2. Verdigris Authorization Server validates the Client ID and Client Secret.

3. Verdigris Authorization Server responds with an Access Token.

4. The application can use the Access Token to make an authorized call to a Verdigris API on behalf of itself.

5. The Verdigris API responds with requested data.

Try the recipe below to authenticate with our Authorization Server and receive an Access Token.