# BaseCite authentication

BaseCite currently uses tenant-scoped API keys for authenticated API and MCP tool access.

## API requests

Send the credential in the documented `x-api-key` header. Credentials are bound to one organization and must not be placed in browser code, public documents, URLs, logs, or prompts.

## MCP requests

Public MCP discovery, `initialize`, `resources/list`, and `resources/read` expose only public documentation. `tools/call` requires the same tenant-scoped API-key boundary.

OAuth 2.0 client credentials are supported for provisioned tenant clients. Discover the authorization server at https://api.basecite.com/.well-known/oauth-authorization-server, exchange the provisioned client credentials at https://api.basecite.com/oauth/token, and resolve the bound organization and scopes at https://api.basecite.com/oauth/identity. Clients must not self-register or exchange an unprovisioned API key for a bearer token.

## Credential provisioning

Credentials are issued or rotated by BaseCite through the approved administrative or secure secret-store workflow. BaseCite does not accept credentials in email, browser code, public issue trackers, URLs, or ordinary chat. The non-secret credential identifier and organization binding may be recorded in deployment metadata; the raw secret must remain in the secret store.

## Request example

```bash
curl --fail-with-body \
  -H 'x-api-key: $BASECITE_TENANT_API_KEY' \
  -H 'Accept: application/json' \
  'https://api.basecite.com/api/v1/organizations/{org_id}/partner-uploads/{upload_id}'
```

For mutations, send a stable `Idempotency-Key` and preserve the returned request and trace identifiers. A `401` or `403` is an authorization boundary, not a signal to guess another credential or organization.

## Supported discovery endpoints

- [OpenAPI contract](https://api.basecite.com/api/v1/ai/openapi.json)
- [MCP metadata](https://mcp.basecite.com/.well-known/mcp.json)
- [MCP server card](https://mcp.basecite.com/.well-known/mcp/server-card.json)
- [Agent plugin manifest](https://basecite.com/plugin.json)

## Discover

Read the [API capabilities](https://api.basecite.com/api/v1/ai/capabilities), [OpenAPI contract](https://api.basecite.com/api/v1/ai/openapi.json), and [MCP metadata](https://mcp.basecite.com/.well-known/mcp.json) before making an authenticated request. The current supported credential is a tenant-scoped API key issued through the authorized admin flow.

## Claim

An organization administrator must establish the organization binding and grant the required upload or AI-read permissions through the controlled admin process. Agents must never self-claim an organization, guess an organization identifier, or reuse a credential from another organization.

## Token exchange

BaseCite supports OAuth 2.0 client credentials for provisioned tenant clients. Discover the authorization server at https://api.basecite.com/.well-known/oauth-authorization-server and the protected resource metadata at https://api.basecite.com/.well-known/oauth-protected-resource. The grant is machine-to-machine only; there is no end-user authorization-code flow.

POST application/x-www-form-urlencoded to https://api.basecite.com/oauth/token with grant_type=client_credentials, client_id equal to the provisioned credential ID, client_secret equal to the tenant credential secret returned once by the authorized admin flow, and an optional space-separated scope subset. The response is a short-lived Bearer access token bound to the same organization and scopes.

## Use credential

Keep the tenant-scoped API key on a server-side integration only. Send it in the documented x-api-key header for authenticated AI-context reads and use the credential-specific upload authorization for partner upload mutations. Bind every request to exactly one org_id; include a stable Idempotency-Key on mutations; verify SHA-256 completion; and poll canonical status until a terminal state.

## Errors

Treat 401 as missing or invalid authentication, 403 as an organization, scope, consent, or visibility boundary, 404 as an upload that is not visible to the credential, 409 as an idempotency or sequence conflict, and 429 as a rate limit. Preserve request_id and trace_id; do not retry with a guessed credential or organization.

## Revocation

Credential revocation is an authorized admin operation. After revocation, stop sending the credential and obtain a newly issued, organization-bound credential through the admin process. Upload withdrawal is separate: use the organization-scoped withdrawal endpoint to delete the original, storage copies, derived AI context, and quota bytes while retaining the deletion receipt and minimum audit metadata.

## Agent authentication discovery

BaseCite publishes API-key and OAuth client-credentials metadata for the current integration surface. OAuth tokens remain tenant-scoped and inherit the provisioned credential's organization binding and granted scopes.