Auth

Authentication and Authorization

User Account Login

Customer Journey: A user signs in to your application using one of the supported identity providers (e.g., "Login with Google" or "Login with Facebook").

Once your mobile or web application user has been authenticated using one of the supported identity providers, and obtained an ID Token, your application needs to exchange that ID Token for an ObjectsGrid Access Token that will provide the required access to all ObjectsGrid APIs:

POST https://apis.objectsgrid.com/oauth2/token/useraccount
Request Headers:
   - "Content-Type": "application/json"
   - "X-ObjectsGrid-RestApiVersion": "stable"
   - "X-ObjectsGrid-SessionID": "you_session_id"
Request Body:
{
  "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
  "subject_token": "your ID Token here",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "client_id": "org-???-????"
}

Request Headers:

• The Content-Type header is mandatory, and should always contain the "application/json" value

• The X-ObjectsGrid-RestApiVersion is optional, and allows you to point to a specific API version. If you provide "stable" it will point to the latest stable API version. If you don't provide the header, it will point you to the stable version of the API as default.

• The X-ObjectsGrid-SessionID header is optional. Allows you to provide your application session id it you need it to be traced in the ObjectsGrid backend.

The Request Body is OAuth2 compliant, and it can be confusing if you are new to OAuth2:

• The grant_type attribute value always needs to be "urn:ietf:params:oauth:grant-type:token-exchange". Don't change anything, just provide it as it is.

• The subject_token attribute value needs to contain your ID Token received from the identity provider your user signed in with.

• The subject_token_type attribute value needs to be "urn:ietf:params:oauth:token-type:id_token". Don't change anything here.

• The client_id attribute value needs to be your Organization Account ID. You got that when you registered your Organization Account.

On successful request processing, you will get back:

HTTP Status Code 201
Response Headers:
   - "Content-Type": "application/json"
   - "Authorization": "Bearer your_new_ObjectGrid_access_token"
Response Body:
{ 
    "access_token": "your_new_ObjectGrid_access_token", 
    "token_type": "Bearer", 
    "expires_in": 14399, 
    "refresh_token": "your_new_ObjectGrid_refresh_token" 
}

The response is also OAuth2 compliant:

• The access_token attribute value contains your newly create access token. You will use it in the subsequent ObjectsGrid API requests.

• The token_type attribute value will always be "Bearer" for this API operation.

• The expires_in attribute value is an integer representing the seconds the token will expire in. Your application should calculate the expiration date time based on the user time zone location, and store that. A few minutes before the expiration, it should refresh the access token using the refresh token.

• The refresh_token attribute value contains your newly created refresh token. You will use it in the subsequent ObjectsGrid API requests to refresh the Access Token. See Refresh Access Token below.

Service Account Login

Customer Journey: Your application or workload uses a Service Account to signs in in order to gain access to the ObjectsGrid APIs. The workload can be a cron job for example, or any program running in your infrastructure that needs to authenticate without user involvement in order to subsequently interact with the ObjectGrid's APIs.

Your workload provides the service account username and password (client_id/client_secret in OAuth2 lingo) via HTTP Basic Authentication, to obtain a ObjectsGrid Access Token that will provide the required access to all ObjectsGrid APIs. For HTTP Basic Authentication, first Base64 encode the concatenated string of the username, a colon (:), and the password ("username:password"). Then, prepend "Basic " (including the space) to the encoded string and set it as the value of the request's Authorization header.

POST https://apis.objectsgrid.com/oauth2/token/serviceaccount
Request Headers:
   - "Authorization": "Basic dXNlcm5hbWU6cGFzc3dvcmQ="
   - "Content-Type": "application/json"
   - "X-ObjectsGrid-RestApiVersion": "stable"
   - "X-ObjectsGrid-SessionID": "you_session_id"
Request Body:
{
  "grant_type": "client_credentials",
}

Request Headers:

• The Authorization header is mandatory, and provides the credentials via HTTP Basic Auth.

• The Content-Type header is mandatory, and should always contain the "application/json" value

• The X-ObjectsGrid-RestApiVersion is optional, and allows you to point to a specific API version. If you provide "stable" it will point to the latest stable API version. If you don't provide the header, it will point you to the stable version of the API as default.

• The X-ObjectsGrid-SessionID header is optional. Allows you to provide your application session id it you need it to be traced in the ObjectsGrid backend.

The Request Body is OAuth2 compliant, but can be confusing if you are new to OAuth2:

• The grant_type attribute value always needs to be "client_credentials". Don't change anything, just provide it as it is.

On successful request processing, you will get back:

HTTP Status Code 201
Response Headers:
   - "Content-Type": "application/json"
   - "Authorization": "Bearer your_new_ObjectGrid_access_token"
Response Body:
{ 
    "access_token": "your_new_ObjectGrid_access_token", 
    "token_type": "Bearer", 
    "expires_in": 14399, 
    "refresh_token": "your_new_ObjectGrid_refresh_token" 
}

The response is OAuth2 compliant:

• The access_token attribute value contains your newly create access token. You will use it in the subsequent ObjectsGrid API requests.

• The token_type attribute value will always be "Bearer" for this API operation.

• The expires_in attribute value is an integer representing the seconds the token will expire in. Your application should calculate the expiration date time based on the user time zone location, and store that. A few minutes before the expiration, it should refresh the access token using the refresh token.

• The refresh_token attribute value contains your newly created refresh token. You will use it in the subsequent ObjectsGrid API requests to refresh the Access Token. See Refresh Access Token below.

Anonymous Login

Customer Journey: Your application needs to provide anonymous access to its customers. For example, you have an ecomm application and you need to allow anonymous access to the Product search and Product details.

Your application uses a service account that does not need a password (API Key) to authenticate with and receive an ObjectsGrid Access Token in order to subsequently interact with the ObjectGrid's APIs.

Your workload provides the service account username and empty password (client_id/client_secret in OAuth2 lingo) via HTTP Basic Authentication, to obtain a ObjectsGrid Access Token that will provide the required access to all ObjectsGrid APIs. For HTTP Basic Authentication, first Base64 encode the concatenated string of the username, a colon (:), and empty password ("username:"). Then, prepend "Basic " (including the space) to the encoded string and set it as the value of the request's Authorization header.

POST https://apis.objectsgrid.com/oauth2/token/serviceaccount
Request Headers:
   - "Authorization": "Basic dXNlcm5hbWU6"
   - "Content-Type": "application/json"
   - "X-ObjectsGrid-RestApiVersion": "stable"
   - "X-ObjectsGrid-SessionID": "you_session_id"
Request Body:
{
  "grant_type": "client_credentials",
}

Request Headers:

• The Authorization header is mandatory, and provides the credentials via HTTP Basic Auth.

• The Content-Type header is mandatory, and should always contain the "application/json" value

• The X-ObjectsGrid-RestApiVersion is optional, and allows you to point to a specific API version. If you provide "stable" it will point to the latest stable API version. If you don't provide the header, it will point you to the stable version of the API as default.

• The X-ObjectsGrid-SessionID header is optional. Allows you to provide your application session id it you need it to be traced in the ObjectsGrid backend.

The Request Body is OAuth2 compliant, but can be confusing if you are new to OAuth2:

• The grant_type attribute value always needs to be "client_credentials". Don't change anything, just provide it as it is.

On successful request processing, you will get back:

HTTP Status Code 201
Response headers:
   - "Content-Type": "application/json"
   - "Authorization": "Bearer your_new_ObjectGrid_access_token"
Response Body:
{ 
    "access_token": "your_new_ObjectGrid_access_token", 
    "token_type": "Bearer", 
    "expires_in": 14399, 
    "refresh_token": "your_new_ObjectGrid_refresh_token" 
}

The response is OAuth2 compliant:

• The access_token attribute value contains your newly create access token. You will use it in the subsequent ObjectsGrid API requests.

• The token_type attribute value will always be "Bearer" for this API operation.

• The expires_in attribute value is an integer representing the seconds the token will expire in. Your application should calculate the expiration date time based on the user time zone location, and store that. A few minutes before the expiration, it should refresh the access token using the refresh token.

• The refresh_token attribute value contains your newly created refresh token. You will use it in the subsequent ObjectsGrid API requests to refresh the Access Token. See Refresh Access Token below.

Refresh Access Token

Customer Journey: A user account, service account, or anonymous have received previously an ObjectsGrid Access Token, and used it successfully to access the ObjectsGrid APIs, but it is going to expire soon, and needs to be refreshed, to prevent prompting again the user or workload for credentials.

To obtain a new Access Token, your application or workload will use the refresh token previously received in auth access token response (see above). The access tokens currently expire in 4 hours, and the refresh tokens in 3 months. Upon refresh, a new access token and a new refresh token are provided. Therefore this mechanism allows for never prompting for credential again if the user or workload are active. As a security mechanism, the refresh tokens can be revoked by admins, see below.

POST https://apis.objectsgrid.com/oauth2/token/refresh
Request Headers:
   - "Content-Type": "application/json"
   - "Authorization": "Bearer your_existing_ObjectGrid_access_token"
   - "X-ObjectsGrid-RestApiVersion": "stable"
   - "X-ObjectsGrid-SessionID": "you_session_id"
Request Body:
{
  "grant_type": "refresh_token",
  "refresh_token": "your existing Refresh Token here"
}

Request Headers:

• The Content-Type header is mandatory, and should always contain the "application/json" value

• The Authorization header is mandatory, and provides the credentials via Bearer Authentication. This header is used for accessing all ObjectsGrid APIs. It should be set by the ObjectsGrid Auth API response. The header value is a sting concatenation of "Bearer " (including the space) and your access token.
• The X-ObjectsGrid-RestApiVersion is optional, and allows you to point to a specific API version. If you provide "stable" it will point to the latest stable API version. If you don't provide the header, it will point you to the stable version of the API as default.

• The X-ObjectsGrid-SessionID header is optional. Allows you to provide your application session id it you need it to be traced in the ObjectsGrid backend.

The Request Body is OAuth2 compliant, and it can be confusing if you are new to OAuth2:

• The grant_type attribute value always needs to be "refresh_token". Don't change anything, just provide it as it is.

• The refresh_token attribute value needs to contain your previously obtained Refresh Token.

On successful request processing, you will get back:

HTTP Status Code 201
Response Headers:
   - "Content-Type": "application/json"
   - "Authorization": "Bearer your_new_ObjectGrid_access_token"
Response Body:
{ 
    "access_token": "your_new_ObjectGrid_access_token", 
    "token_type": "Bearer", 
    "expires_in": 14399, 
    "refresh_token": "your_new_ObjectGrid_refresh_token" 
}

The response is also OAuth2 compliant:

• The access_token attribute value contains your newly create access token. You will use it in the subsequent ObjectsGrid API requests.

• The token_type attribute value will always be "Bearer" for this API operation.

• The expires_in attribute value is an integer representing the seconds the token will expire in. Your application should calculate the expiration date time based on the user time zone location, and store that. A few minutes before the expiration, it should refresh the access token using the refresh token.

• The refresh_token attribute value contains your newly created refresh token. You will use it in the subsequent ObjectsGrid API requests to refresh the Access Token.

Revoke Refresh Token

Customer Journey: One of your refresh tokens was stolen. Your administrator needs a way to revoke it.

A refresh token is a long-lived credential used to obtain a new access token without requiring user authentication. While refresh tokens improve security by limiting access token exposure, they also introduce risks. Revoking a refresh token is essential for maintaining security and access control. If a refresh token is leaked, stolen, or exposed, an attacker can use it to continuously obtain new access tokens, maintaining unauthorized access.

To revoke a refresh token, your administrator can use the revoke operation

POST https://apis.objectsgrid.com/oauth2/token/revoke
Request Headers:
   - "Content-Type": "application/json"
   - "Authorization": "Bearer your_existing_ObjectGrid_access_token"
   - "X-ObjectsGrid-RestApiVersion": "stable"
   - "X-ObjectsGrid-SessionID": "you_session_id"
Request Body:
{
  "token": "the refresh token to be revoked",
  "token_type_hint": "refresh_token"
}

Request Headers:

• The Content-Type header is mandatory, and should always contain the "application/json" value

• The Authorization header is mandatory, and provides the credentials via Bearer Authentication. This header is used for accessing all ObjectsGrid APIs. It should be set by the ObjectsGrid Auth API response. The header value is a sting concatenation of "Bearer " (including the space) and your access token.
• The X-ObjectsGrid-RestApiVersion is optional, and allows you to point to a specific API version. If you provide "stable" it will point to the latest stable API version. If you don't provide the header, it will point you to the stable version of the API as default.

• The X-ObjectsGrid-SessionID header is optional. Allows you to provide your application session id it you need it to be traced in the ObjectsGrid backend.

The Request Body is OAuth2 compliant, and it can be confusing if you are new to OAuth2:

• The token attribute value needs to contain the Refresh Token to be revoked.

• The token_type_hint attribute value always needs to be "refresh_token". Don't change anything, just provide it as it is.

On successful request processing, you will get back:

HTTP Status Code 200
Response Headers:
   - "Content-Type": "application/json"
Response Body:
 empty

The response is also OAuth2 compliant:

• The HTTP status code will be 200 for successful revoke, and also for previously revoked refresh tokens, to be compliant with the OAuth2 standard.

• The body will be empty on successful revoke

---

Contact Support

---