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 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 second per IP address
  • Sandbox: 2500 requests per second 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.


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