Oauth

  1. Home
  2. API Library
  3. Oauth
The key to secure access to all APIs.

Oauth is the authentication service for API usage and provides secure management of requests and integrations

All the knowledge you need

Here you can find some advice to consider to approach this API. If you prefer, we provide code samples, OAS3 documentation, the ability to try the API live via the Swagger UI or import the entire collection into Postman. We also offer a Sandbox environment where you can experiment with all kinds of requests completely free of charge.

Useful tips to start with Oauth

Check your APIkey in the appropriate section before you start.

Use your email and your APIkey to create your "Basic Auth" header and perform request on Tokens, Scopes, Credit and Counters
Check my APIkey

Create you first Token.

A token is a small key used to authenticate all your further requests to any API. It has 2 main attributes: "Scope" and "TTL". "Scopes" is a list of actions available from the authenticated request with the generated token. "TTL" defines the expiration date and time this Token will have. For security reasons it is better to set tokens to expire quickly.
Check how to create a token

Check your Credit via API.

We provide planty of configurations to setup alerts and notifications based on your remaining credit. SMS, EMAIL or the Autorecharge feature are available.
If you prefer, you can do it by your own using APIs.
Check how to obtain your credit Setup credit based notifications

Get your stats via API.

In each API you will find the "Usage" section where you can consult the usage status for each individual Scope through graphs and aggregated data.
In case you need raw usage data to build your dashboard or set up a usage-based notification system, we provide an endpoint specifically for this purpose.
Check how to obtain your usage counters
API docs by Redocly

Oauth (1.0.0)

URL: https://openapi.it/en/support License: Apache 2.0 Terms of Service

Oauth is our essential authentication web service to use our services safely. Through this service you can receive, modify and see essential tokens to access all the rest methods of the bees that we provide.

Check out more at https://developers.openapi.it/services/oauth
Explore all our services at https://developers.openapi.it/services

First time here? Generate a new access token

token

Receive, view and edit all tokens associated with your account

Receive a token

With this call passing one or more scopes you receive a token that you will need to authenticate with the same scopes you passed. Tokens with expiration dates can be very useful if you want to restrict access to just the small number of scopes that your application/service needs: in this way you can avoid unwanted requests

Authorizations:
basicAuth
Request Body schema: application/json
scopes
required
Array of strings

List of scopes for which you want to be authorized to use; you can also pass an asterisk as a wild card for all methods or all domains or all endpoints. For example if I want all the methods and endpoints of a given domain '*:comparabili.openapi.it/*'; if I want all the scopes '*:*/*'

expire
integer
Deprecated
ttl
integer

The token lifespan (time-to-live) in seconds, up to one year; if not provided, when creating a token it will be set to expire in 1 year from now. The example shows how to request a token that has a lifespan of 30 days.

Responses

Response Schema: application/json
scopes
Array of strings

A list of the scopes you requested, expanded

expire
integer

A UNIX timestamp, in seconds, rappresenting the expiring date of the token

token
string

Your new token

success
boolean
message
string
error
integer

Request samples

Content type
application/json
{
  • "scopes": [
    ],
  • "expire": 0,
  • "ttl": 2592000
}

Response samples

Content type
application/json
{
  • "scopes": [
    ],
  • "expire": 1634223407,
  • "token": "5f8711afe4754a532a7a8358",
  • "success": true,
  • "message": "",
  • "error": null
}

List of all unexpired token

Method that returns all the tokens with their scopes still active for your account

Authorizations:
basicAuth
query Parameters
scope
string
Example: scope=GET:imprese.openapi.it/base

name of the scope for which to filter the tokens

Responses

Response Schema: application/json
Array of objects
success
boolean
message
string
error
integer

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://oauth.openapi.it/token?scope=SOME_STRING_VALUE");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Basic REPLACE_BASIC_AUTH");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "success": true,
  • "message": "",
  • "error": null
}

Finds a specific token

Method that returns the token you passed in the path

Authorizations:
basicAuth
path Parameters
token
required
string
Example: 5f8041e42efdfc468b6e60ea

requested token

Responses

Response Schema: application/json
Array of objects
success
boolean
message
string
error
integer

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://oauth.openapi.it/token/5f8041e42efdfc468b6e60ea");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Basic REPLACE_BASIC_AUTH");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "success": true,
  • "message": "",
  • "error": null
}

Update the entire token object

Method that allows you to modify the entire token object by passing it new ones or the same reference scopes with a new expiration

Please note that the TTL option is not available for this method.

Authorizations:
basicAuth
path Parameters
token
required
string
Example: 5f8041e42efdfc468b6e60ea

requested token

Request Body schema: application/json
scopes
required
Array of strings

List of scopes for which you want to be authorized to use; you can also pass an asterisk as a wild card for all methods or all domains or all endpoints. For example if I want all the methods and endpoints of a given domain '*:comparabili.openapi.it/*'; if I want all the scopes '*:*/*'

expire
integer

An expiration date in expressed as a UNIX timestamp in seconds. If not set, the date will be set one year from now

Responses

Response Schema: application/json
Array of objects
success
boolean
message
string
error
integer

Request samples

Content type
application/json
{
  • "scopes": [
    ],
  • "expire": 1660640780
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "success": true,
  • "message": "",
  • "error": null
}

Update part of token object

Method that allows you to modify individual fields of the token object by passing it new ones or the same reference scopes or a new expiration

Authorizations:
basicAuth
path Parameters
token
required
string
Example: 5f8041e42efdfc468b6e60ea

requested token

Request Body schema: application/json
scopes
required
Array of strings

List of scopes for which you want to be authorized to use; you can also pass an asterisk as a wild card for all methods or all domains or all endpoints. For example if I want all the methods and endpoints of a given domain '*:comparabili.openapi.it/*'; if I want all the scopes '*:*/*'

expire
integer
Deprecated
ttl
integer

The token lifespan (time-to-live) in seconds, up to one year; if not provided, when creating a token it will be set to expire in 1 year from now. The example shows how to request a token that has a lifespan of 30 days.

Responses

Response Schema: application/json
Array of objects
success
boolean
message
string
error
integer

Request samples

Content type
application/json
{
  • "scopes": [
    ],
  • "expire": 0,
  • "ttl": 2592000
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "success": true,
  • "message": "",
  • "error": null
}

Delete a specific token

Method that allows you to delete a token object from your account

Authorizations:
basicAuth
path Parameters
token
required
string
Example: 5f8041e42efdfc468b6e60ea

requested token

Responses

Response Schema: application/json
success
boolean
message
string
error
integer

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_easy_setopt(hnd, CURLOPT_URL, "https://oauth.openapi.it/token/5f8041e42efdfc468b6e60ea");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Basic REPLACE_BASIC_AUTH");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
{
  • "message": "1 deleted token",
  • "success": true,
  • "error": null
}

scopes

Get a list of scopes associated with your account

List of all scopes

Method that returns the list of all scopes for which you have requested the token and therefore associated with your account

Authorizations:
basicAuth

Responses

Response Schema: application/json
data
Array of strings
success
boolean
message
string
error
integer

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://oauth.openapi.it/scopes");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Basic REPLACE_BASIC_AUTH");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "success": true,
  • "message": "",
  • "error": null
}

credit

Your Openapi credit

Your Openapi credit

Method that returns your remaining Openapi credit

Authorizations:
basicAuth

Responses

Response Schema: application/json
object
success
boolean
message
string
error
integer

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://oauth.openapi.it/credit");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Basic REPLACE_BASIC_AUTH");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true,
  • "message": "",
  • "error": null
}

counters

Get your usage stats

Your overall use

Get your usage stats by scope

Authorizations:
basicAuth

Responses

Response Schema: application/json
object
success
boolean
message
string
error
integer

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://oauth.openapi.it/counters/total");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Basic REPLACE_BASIC_AUTH");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true,
  • "message": "",
  • "error": null
}

Usage stats for a specific day

Get your usage stats by scope

Authorizations:
basicAuth
path Parameters
token
required
string
Example: 2022-01-01

The requested date, in YYYY-MM-DD format. Months and days should be with leading zeros.

Responses

Response Schema: application/json
object
success
boolean
message
string
error
integer

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://oauth.openapi.it/counters/day/%7Bday%7D");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Basic REPLACE_BASIC_AUTH");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true,
  • "message": "",
  • "error": null
}

Usage stats for a specific month

Get your usage stats by scope

Authorizations:
basicAuth
path Parameters
token
required
string
Example: 2022-01

The requested date, in YYYY-MM format. Months should be with leading zeros.

Responses

Response Schema: application/json
object
success
boolean
message
string
error
integer

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://oauth.openapi.it/counters/month/%7Bmonth%7D");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Basic REPLACE_BASIC_AUTH");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true,
  • "message": "",
  • "error": null
}

Usage stats for a specific year

Get your usage stats by scope

Authorizations:
basicAuth
path Parameters
token
required
string
Example: 2022

The requested date, in YYYY format.

Responses

Response Schema: application/json
object
success
boolean
message
string
error
integer

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://oauth.openapi.it/counters/year/%7Byear%7D");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Basic REPLACE_BASIC_AUTH");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true,
  • "message": "",
  • "error": null
}
Web Service Revision: 2.0.0