# auth.md

OmniCommerce agent registration metadata and instructions for commerce agents and MCP clients.

## OmniCommerce Agent Authentication

OmniCommerce exposes public discovery endpoints plus protected MCP and developer APIs. Agents register by creating an organization-scoped OAuth client, then exchanging the client credentials for bearer access tokens.

## Step 1 - Discover

Fetch the public discovery documents before registering:

- Protected resource metadata: https://omnicommerce.sg/.well-known/oauth-protected-resource
- Authorization server metadata: https://omnicommerce.sg/.well-known/oauth-authorization-server
- Auth instructions: https://omnicommerce.sg/auth.md
- API documentation: https://omnicommerce.sg/docs/mcp#authentication

## Step 2 - Pick a Registration Method

Supported registration method:

- Method: `organization_user_session`
- Audience: agents acting for an authenticated OmniCommerce organization user
- Registration URI: https://omnicommerce.sg/api/oauth-clients
- Required identity: an active OmniCommerce user session with access to the target `organizationId`
- Credential issued: OAuth 2.0 client credentials
- Token endpoint: https://omnicommerce.sg/api/oauth/token
- Revocation endpoint: https://omnicommerce.sg/api/oauth/revoke

Unsupported Auth.md identity flows:

- `identity_assertion` / ID-JAG agent-verified registration
- `service_auth` email claim ceremony
- `anonymous` pre-claim registration

## Step 3 - Register

Create an OAuth client with an authenticated organization user session:

```http
POST /api/oauth-clients HTTP/1.1
Host: omnicommerce.sg
Content-Type: application/json
Cookie: <authenticated OmniCommerce session>
```

Request body:

```json
{
  "organizationId": "org_...",
  "name": "My agent integration",
  "description": "Catalog and MCP access for my agent",
  "isActive": true
}
```

Successful response:

```json
{
  "client": {
    "id": "client_id",
    "organizationId": "org_...",
    "name": "My agent integration",
    "isActive": true,
    "scopes": ["mcp:read", "mcp:tools:call"]
  },
  "clientSecret": "omni_sk_live_..."
}
```

The `clientSecret` is returned once. Store it securely and use it with `client.id` at the token endpoint.

## Step 4 - Exchange Credentials

Exchange the OAuth client credentials for a bearer access token:

```http
POST /api/oauth/token HTTP/1.1
Host: omnicommerce.sg
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>&scope=mcp:read mcp:tools:call
```

Successful response:

```json
{
  "access_token": "<bearer_token>",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

## Step 5 - Use the Credential

Present the access token in the HTTP Authorization header:

```http
GET /api/mcp HTTP/1.1
Host: omnicommerce.sg
Authorization: Bearer <bearer_token>
```

## Step 6 - Revoke a Token

Revoke an issued access token with the same client credentials:

```http
POST /api/oauth/revoke HTTP/1.1
Host: omnicommerce.sg
Content-Type: application/x-www-form-urlencoded

token=<bearer_token>&token_type_hint=access_token&client_id=<client_id>&client_secret=<client_secret>
```

A successful revocation returns HTTP 200 with an empty body.

## Supported Scopes

- mcp:read
- mcp:tools:call
- catalog:write
- catalog:evaluate
- catalog:enrich
- catalog:sync
- catalog:monitor
- webhooks:manage
- checkout:write
- orders:read
- orders:write
- promotions:read
- promotions:write

```agent_auth
version: 1
skill: https://omnicommerce.sg/auth.md
register_uri: https://omnicommerce.sg/api/oauth-clients
registration_documentation: https://omnicommerce.sg/docs/mcp#authentication
registration_methods_supported:
  - organization_user_session
registration_methods:
  - type: organization_user_session
    name: Authenticated organization OAuth client registration
    register_uri: https://omnicommerce.sg/api/oauth-clients
    required_identity: authenticated_organization_member
    credential_types_supported:
      - oauth2_client_credentials
    token_endpoint: https://omnicommerce.sg/api/oauth/token
    revocation_uri: https://omnicommerce.sg/api/oauth/revoke
identity_types_supported:
  - organization_user_session
credential_types_supported:
  - oauth2_client_credentials
  - api_key_bearer
authorization_servers:
  - https://omnicommerce.sg
authorization_server_metadata: https://omnicommerce.sg/.well-known/oauth-authorization-server
protected_resources:
  - https://omnicommerce.sg/.well-known/oauth-protected-resource
token_endpoint: https://omnicommerce.sg/api/oauth/token
revocation_uri: https://omnicommerce.sg/api/oauth/revoke
grant_types_supported:
  - client_credentials
scopes_supported:
  - mcp:read
  - mcp:tools:call
  - catalog:write
  - catalog:evaluate
  - catalog:enrich
  - catalog:sync
  - catalog:monitor
  - webhooks:manage
  - checkout:write
  - orders:read
  - orders:write
  - promotions:read
  - promotions:write
unsupported_identity_types:
  - anonymous
  - identity_assertion
  - service_auth
```