All requests to the Sivo API must be made over HTTPS, which provides end-to-end encryption over the network.

Sivo uses the OAuth2 standard to authenticate API requests. OAuth2 is widely adopted and makes it possible for Sivo to integrate with other applications. You don't need to understand the entire OAuth spec to connect to Sivo. The important thing to know is that OAuth2 uses two types of tokens:

  • Refresh Token: you can think of the refresh token as the main credentials (or api key) used to authenticate to the Sivo API. You use the refresh token to obtain an access token (see below). You can retrieve a refresh token from the Sivo application by going to Integrations (see Testing for details regarding Sandbox vs Live environments). The refresh token represents credentials for the current user. API requests will execute under the same authorization context as the end user that obtained the refresh token. Refresh tokens expire after 10 years and can be revoked if you believe that the token might have been compromised.
  • Access Token: sometimes referred to as a "Session Token", this is a short-lived (60 minutes) token that is used to invoke the Sivo APIs. The access token should be included in the Authorization header of any API requests. Sivo will verify that the access token is valid and has access to the appropriate resources.

The 60 minute limit for access tokens is typically sufficient for most use cases. If you are making multiple requests over a short period of time, you should cache the access token and reuse across requests for better performance. If the access token expires Sivo will respond with a 401 (Unauthorized) status code. In this case you can request a fresh access token to continue using the Sivo APIs.