> For the complete documentation index, see [llms.txt](https://docs.we360.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.we360.ai/deployment-and-it-ops/integrations-and-api-access/integrations/oauth-for-direct-api-access.md).
# OAuth for Direct API Access
Use OAuth authorization to connect custom apps and call We360.ai APIs directly.
Use this path when you need a custom integration. It is the right option for direct API access.
## API guides
Guide
Description
Open
Dynamic Report API
Fetch employee activity and attendance analytics with explicit field selection.
## Overview
The we360.ai API uses OAuth 2.0 Resource Owner Password Credentials.
A successful login returns:
* `access_token`
* `refresh_token`
The flow is:
1. Call the Login API with your Customer ID, email, and password.
2. Receive an `access_token` and `refresh_token`.
3. Send the `access_token` as a Bearer token in every API request.
4. Call the Refresh Token API when the `access_token` expires.
5. Call the Login API again if the `refresh_token` is no longer valid.
{% hint style="info" %}
The `access_token` is valid for 10 hours. This value may change.
{% endhint %}
## Login API
Use this endpoint to authenticate and get the first token pair.
**Endpoint**
```
POST https://auth.in.we360.ai/realms/ind-prod/protocol/openid-connect/token
```
**cURL example**
```bash
curl --location \
'https://auth.in.we360.ai/realms/ind-prod/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode "client_id=${customer_id}" \
--data-urlencode "username=${email}" \
--data-urlencode "password=${password}" \
--data-urlencode "grant_type=password"
```
### Request parameters
| Parameter | Description |
| ------------ | --------------------------------------------------------------------------------------------------- |
| `client_id` | Your Customer ID. Retrieve it from the profile icon in the top-right corner of the we360.ai portal. |
| `username` | The registered email address associated with your we360.ai account. |
| `password` | The password for your we360.ai account. |
| `grant_type` | Must be `password`. |
**Sample response**
```json
{
"access_token": "eyJhbG...8qA1Klw",
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR...x78q-gRk2-lLHV53L0",
"token_type": "Bearer",
"not-before-policy": 0,
"session_state": "bb62faa8-1b33-4d8e-966b-88120e39670a",
"scope": "email offline_access profile"
}
```
### Response fields
| Field | Description |
| ------------------- | ----------------------------------------------------------------------------- |
| `access_token` | JWT used to authenticate API requests. Valid for 10 hours, subject to change. |
| `refresh_token` | Used to obtain a new `access_token` without logging in again. |
| `token_type` | Always `Bearer`. |
| `not-before-policy` | Keycloak policy timestamp. Usually `0`. |
| `session_state` | UUID for the active authentication session. |
| `scope` | Granted scopes such as `email`, `profile`, and `offline_access`. |
{% hint style="info" %}
To retrieve your Customer ID, click the profile icon in the top-right corner of the we360.ai portal. You can copy it directly from there.
{% endhint %}
## Refresh Token API
Use this endpoint to get a new token pair when the current `access_token` expires.
**Endpoint**
```
POST https://auth.in.we360.ai/realms/ind-prod/protocol/openid-connect/token
```
**cURL example**
```bash
curl --location \
'https://auth.in.we360.ai/realms/ind-prod/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=${customer_id}' \
--data-urlencode 'refresh_token=${refresh_token}' \
--data-urlencode 'grant_type=refresh_token'
```
### Request parameters
| Parameter | Description |
| --------------- | --------------------------------------------------------------------------- |
| `client_id` | Your Customer ID. Use the same value used during login. |
| `refresh_token` | The `refresh_token` returned by a previous Login or Refresh Token response. |
| `grant_type` | Must be `refresh_token`. |
**Sample response**
```json
{
"access_token": "eyJhbG...8qA1Klw",
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR...x78q-gRk2-lLHV53L0",
"token_type": "Bearer",
"not-before-policy": 0,
"session_state": "bb62faa8-1b33-4d8e-966b-88120e39670a",
"scope": "email offline_access profile"
}
```
{% hint style="warning" %}
If the Refresh Token API returns a non-200 status, the `refresh_token` has expired or was invalidated. Call the Login API again to get a fresh token pair.
{% endhint %}
## Use the bearer token
Send the `access_token` in the `Authorization` header of every API request:
```
Authorization: Bearer ${access_token}
```
**Example**
```bash
curl --location 'https://api.in.we360.ai/v1/some-endpoint' \
--header 'Authorization: Bearer eyJhbG...8qA1Klw' \
--header 'Content-Type: application/json'
```
{% hint style="danger" %}
Bearer tokens are sensitive credentials. Never expose them in client-side code, URLs, logs, or version control. Always send them over HTTPS.
{% endhint %}
## Token lifecycle and best practices
| Token | Expiry | On expiry |
| --------------- | -------------------- | -------------------------- |
| `access_token` | 10 hours, may change | Call the Refresh Token API |
| `refresh_token` | Server-defined | Call the Login API again |
Additional recommendations:
* Store tokens securely. Use environment variables or a secrets manager.
* Refresh proactively. Check expiry before each request.
* Always store the newest `access_token` and `refresh_token`.
* Use HTTPS only.
* Revoke the session on logout if your application supports it.
If your environment restricts outbound traffic, allow the required domains listed in [The "Allowlist" Guide](/deployment-and-it-ops/security-hardening/network-security-hardening/allowlist-guide.md).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.we360.ai/deployment-and-it-ops/integrations-and-api-access/integrations/oauth-for-direct-api-access.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.