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:

Code Name Description
200 OK The request was successful.
201 Created The request created a new resource.

4xx series response codes

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

Code Name Description
400 Bad Request The request cannot be understood, likely because it is malformed / has invalid syntax.
401 Unauthorized The request lacks a bearer token, or the bearer token is expired. See section above for more detail.
422 Unprocessable Entity The request contains validation errors. Validations will vary by API, so check the relevant API specification.
429 Too Many Requests The request is being rate limited. See section below for more detail.

Example response body for a 422 status code:

   "message": "Validation Failed",
         "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:

Code Name Description
500 Internal Server Error The request failed because of an unexpected sever error.
502 Bad Gateway The request was not able to reach the upstream server.
503 Service Unavailable The request failed because the upstream server did not respond in time.

Rate Limiting

Optoro seeks to avoid rate limiting our customers, and in most cases it should not be a concern. The number of threads or processes making simultaneous requests to an API is more important than the rate of requests. If you limit requests to a single thread or process, then you do not need to worry about rate limiting. If more throughput is needed than a single thread/process can provide, you can increase the number of threads/process after discussing with a member of Optoro's Client Success team.

In the rare event that a high volume of traffic threatens our system, Optoro reserves the right to rate limit. Rate limited requests will receive a 429 HTTP response status code. Your system should respond by adding an exponential backoff between requests and retrying.

TLS and SSL Certificate Security Specifications

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

Let’s Encrypt root certificates must be installed on all machines that communicate with Optoro APIs. These certificates are preinstalled on many platforms. Compatibility is detailed here.

© 2010 – 2024 Optoro, Inc. For official use only by authorized users. Use subject to terms of license agreement.