The OAuth 2.0 Client Credentials flow for server-to-server communication is used by Gridsz when a specific user account is not required. New integrations are required to use OAuth 2.0 Client Credentials, while existing integrations are strongly advised to migrate from JWT Bearer Tokens to OAuth 2.0 to benefit from automated token rotation and enhanced security controls.

OAuth 2.0, an industry standard method for secure, automated data exchange between applications, is used for the following use cases:

• System-to-System Integration: The connection is strictly between applications (machine-to-machine) rather than individual users.
• Enhanced Security: Access relies on short-lived tokens rather than permanent credentials. If a token is compromised, the exposure window is limited to the token’s lifespan (e.g., 24 hours).
• Automated Lifecycle: Tokens expire automatically and must be programmatically renewed, ensuring continuous validation of access rights.
• Centralized Management: Credentials can be rotated or revoked centrally without requiring code deployments or manual intervention in the integrating application.
• Industry Standard: This protocol aligns with modern enterprise security best practices for API authentication.

Prerequisites

Before starting, ensure you have the following:

1. Client ID (provided by Gridsz)
2. Client Secret (provided by Gridsz  – must be stored securely)
3. Token Endpoint URL, for example https://api.task.gridsz.com/connector/api/v1/authorization/connect/token
4. Permission to access the Connector API (third-party API access enabled by Gridsz)

Step 1. Get Access Token

The client requests an access token by calling the token endpoint using the Client Credentials grant.

HTTP Request

POST /authorization/connect/token

Content-Type: application/x-www-form-urlencoded

Request Body

grant_type=client_credentials

&client_id=YOUR_CLIENT_ID

&client_secret=YOUR_CLIENT_SECRET

&scope=api.read api.write   (optional)

💡 This request can be tested easily using Postman.

Step 2. Token Response

If the request is successful, the authorization server returns an access token:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 86400
}

• access_token: Token used to call protected APIs
• expires_in: Token validity in seconds (24 hours)

Step 3. Calling the Protected API

(fetch, indication, sync)

Use the access token from the previous step in the Authorization header when calling the Connector API.

Example: Fetch task request

GET https://api.task.gridsz.com/connector/api/v1/sp/{orgId}/tasks/{inId}

Authorization: Bearer <ACCESS_TOKEN>

Common Errors

If errors persist, verify credentials and ensure the client is authorized to access the Connector API.