Goa-gel-fullstack/Documentation/developers/authentication.md

# Authentication

## Overview

The platform uses OAuth 2.0 with JWT tokens for API authentication.

## Obtaining Credentials

Contact your administrator to receive:
- Client ID
- Client Secret
- Authorized scopes

## Token Request

```http
POST /auth/token HTTP/1.1
Host: api.license.gov.in
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
scope=applications:read applications:write
```

### Response

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "applications:read applications:write"
}
```

## Using the Token

Include token in Authorization header:

```http
GET /applications/APP-2026-00001 HTTP/1.1
Host: api.license.gov.in
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
```

## Token Refresh

Tokens expire after 1 hour. Request new token before expiry.

## Available Scopes

| Scope | Access |
|-------|--------|
| `applications:read` | View applications |
| `applications:write` | Submit and update applications |
| `documents:read` | View documents |
| `documents:write` | Upload documents |
| `verification:read` | Verify certificates |

## DigiLocker OAuth

For citizen authentication via DigiLocker:

```http
GET /auth/digilocker/authorize?
  redirect_uri=https://yourapp.com/callback&
  state=random_state_value
```

User is redirected to DigiLocker. After consent, user returns with authorization code.

## Error Codes

| Code | Description |
|------|-------------|
| `invalid_client` | Unknown client ID |
| `invalid_grant` | Invalid credentials |
| `invalid_scope` | Requested scope not authorized |
| `expired_token` | Token has expired |