# OrgOrg API v1 — Authentication — instructions for AI agents

This document describes the Authentication endpoints of the OrgOrg v1 REST API. Fetch it from https://orgorg.com/docs/api/v1/auth/agents.md. The full API is documented at https://orgorg.com/docs/api/v1/agents.md.

## Basics

- Base URL: `https://orgorg.com`. All endpoint paths below are relative to it.
- Every request requires an `Authorization: Bearer <token>` header.
- `GET` endpoints take parameters in the URL query string. `POST` endpoints take a JSON body with a `Content-Type: application/json` header.
- All responses are JSON. A non-2xx status means the request failed; the body describes the problem.
- Endpoints are stable, but new response fields may be added without notice — ignore fields you do not recognize.

## Getting a token

Tokens are created by a signed-in user at https://orgorg.com/docs/credentials and inherit that user's permissions in their organization. If you do not have a token, ask your user to create one there. Verify a token works with:

```sh
curl "https://orgorg.com/api/v1/auth/test" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN"
```

A valid token returns `{ "ok": true, ... }`.

## Authentication

Validate API tokens. Human-readable docs: https://orgorg.com/docs/api/v1/auth

### Test authentication

`GET /api/v1/auth/test`

Validate the API access token is valid and working

Parameters: none.

Example request:

```sh
curl -X GET "https://orgorg.com/api/v1/auth/test" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN"
```

Response shape:

```ts
{
  ok: boolean:
  scopes: string[]:
  message: string
}
```