API Overview

The following information applies to all of Optoro's inbound APIs, i.e. your system sending requests to Optoro's system.

Authentication and Authorization

Optoro uses the OAuth 2.0 client credentials flow for server-to-server authentication. Optoro's Client Success team will provide the credentials used when requesting an access token. Include the access token in subsequent requests to Optoro APIs.

Access tokens are valid for 25 hours and should be reused. There is no need to request a new token until the previous token expires. The same token may be used across all of Optoro's APIs.

Requesting an Access Token

Call the OAuth token endpoint and include the client_id and client_secret values provided by Optoro's Client Success team. See the Auth API specification for more details.

Sample Request

POST https://auth.optiturn.com/oauth/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "f2449833d49b9646a701d2423bef8ec9a49",
  "client_secret": "1d98065fc19939c10d26909f9aa58d2b5ef"
}

Sample Response

{
  "access_token": "8xB2vvU4ytrl1zYQ_EdGUQrdFJmuCMck",
  "token_type": "Bearer",
  "expires_in": 90000,
  "scope": "read write",
  "created_at": 1683235103
}

Use the value of the access_token field to authenticate subsequent API calls. The expiration period of the token is expressed in seconds.

HTTP Request Headers

Requests to Optoro APIs should include a common set of HTTP headers. Optoro APIs:

• Are authorized using bearer tokens
• Accept request bodies formatted as JSON
• Expect request bodies are encoded as valid UTF-8
• Return responses formatted as JSON

Authorization: bearer {access_token}
Content-Type: application/json
Accept: application/json

Replace {access_token} in this example with the value provided in the response from the OAuth token endpoint documented in the previous section.

Some APIs are versioned using an HTTP header. The header name and value will vary by API, so check the relevant API specification. For example:

X-Optiturn-Api-Version: 1

HTTP Responses

Optoro APIs use a standard set of HTTP response status codes to indicate the result of a request. Response bodies are formatted as JSON. Responses will vary by API, so check the relevant API specification.

2xx series response codes

The request was successfully received, understood, and accepted. Common codes include:

4xx series response codes

A client error prevented the request from succeeding. You must take action before trying the request again. Common codes include:

Example response body for a 422 status code:

{
   "message": "Validation Failed",
   "errors":[
      {
         "field": "rma_identifier",
         "code": "missing_field"
      }
   ]
}

5xx series response codes

A server error prevented the request from succeeding. You should try the request again. These responses will be rare, and retrying the request often resolves the issue. We recommend retrying three times with an exponential backoff between each request. Escalate to Optoro's Client Support team if the error persists. Common codes include:

Rate Limiting

Optoro reserves the right to rate limit in the event that a high volume of traffic threatens our system. Rate limited requests will receive an HTTP 429 Too Many Requests response status code. Your system should react by retrying the request with an exponential backoff between each attempt.

Rate Limits:

• Production: 5000 requests per minute per IP address
• Sandbox: 2500 requests per minute per IP address

TLS and SSL Certificate Security Specifications

Optoro only supports communication between servers via HTTPs using TLS 1.2. Optoro SSL certificates are provided by Google Trust Services and Let's Encrypt.

Google root certificates and Let’s Encrypt root certificates must be installed on all machines that communicate with Optoro APIs. These certificates are preinstalled on many platforms.

Compatibility:

• Google
• Let's Encrypt