# auth.md

> This document describes how AI agents and automated clients can register and authenticate with StaffKhata APIs.

## About StaffKhata

StaffKhata is an AI-powered HRMS, Payroll, and Field Workforce Management platform for businesses across India and beyond.

- **Platform**: https://staffkhata.com
- **API Base**: https://staffkhata.com/api
- **Documentation**: https://staffkhata.com/docs/api

## Agent Registration

Agents can register as OAuth 2.0 clients using Dynamic Client Registration:

- **Registration Endpoint**: https://staffkhata.com/oauth/register
- **Authorization Server**: https://staffkhata.com
- **Discovery**: https://staffkhata.com/.well-known/openid-configuration

## Authentication Methods

### 1. Authorization Code + PKCE (Recommended for user-delegated agents)

```
GET https://staffkhata.com/oauth/authorize
  ?response_type=code
  &client_id={your_client_id}
  &redirect_uri={your_redirect_uri}
  &scope=attendance:read payroll:read employees:read
  &code_challenge={code_challenge}
  &code_challenge_method=S256
```

### 2. Client Credentials (For autonomous agents)

```
POST https://staffkhata.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id={your_client_id}
&client_secret={your_client_secret}
&scope=attendance:read employees:read
```

### 3. Device Authorization (For headless/CLI agents)

```
POST https://staffkhata.com/oauth/device/code
Content-Type: application/x-www-form-urlencoded

client_id={your_client_id}
&scope=attendance:read
```

## Supported Scopes

| Scope | Description |
|---|---|
| `attendance:read` | View attendance records |
| `attendance:write` | Create and update attendance |
| `payroll:read` | View payroll and salary data |
| `payroll:write` | Process payroll |
| `employees:read` | View employee profiles |
| `employees:write` | Create and update employees |
| `reports:read` | Access analytics and reports |

## Token Usage

Include the access token as a Bearer token in the `Authorization` header:

```
Authorization: Bearer {access_token}
```

## Token Revocation

```
POST https://staffkhata.com/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token={access_token}
&client_id={your_client_id}
```

## Identity Assertion (ID-JAG)

Agents with verifiable identity can use identity assertions:

- **Assertion Type**: `urn:ietf:params:oauth:token-type:id-jag`
- **Claim URI**: https://staffkhata.com/oauth/claim
- **Revocation URI**: https://staffkhata.com/oauth/revoke

## Protected Resource Metadata

Machine-readable OAuth Protected Resource Metadata is available at:
`/.well-known/oauth-protected-resource`

## Contact

For agent integration support: support@staffkhata.com