# OverSkill auth.md

This document is for **autonomous agents** (and the developers building
them) that need to authenticate against the OverSkill API. It is the
human-readable companion to the machine-readable discovery documents:

- **OAuth Authorization Server Metadata** (RFC 8414):
  `https://dev.overskill.com/.well-known/oauth-authorization-server`
  — also carries the structured `agent_auth` block.
- **OAuth Protected Resource Metadata** (RFC 9728):
  `https://dev.overskill.com/.well-known/oauth-protected-resource`
- **MCP Server Card** (SEP-1649):
  `https://dev.overskill.com/.well-known/mcp/server-card.json`

## Audience

You are an AI agent that wants to read or build apps on OverSkill on
behalf of a user. Start unauthenticated if you only need the anonymous
build flow; authenticate when you need to act inside a user's team.

## What we support

- **OAuth 2.0 Authorization Code + PKCE** (`S256`) — the recommended
  flow for agents acting on behalf of a user.
- **Opaque bearer tokens** — present the access token as
  `Authorization: Bearer <token>` on every API request.
- **API keys** — alternatively send `X-API-Key: <key>` for
  server-to-server access. Obtain one at `https://dev.overskill.com/account/api_keys`.

We do **not** implement Dynamic Client Registration: OverSkill apps are
provisioned as first-class OAuth clients, so there is no runtime
`registration_endpoint`. We do **not** implement ID-JAG or anonymous /
ephemeral identity tokens.

## Provisioning / registration

1. Direct the user's browser to the authorize endpoint:
   `https://dev.overskill.com/oauth/authorize`
   with `response_type=code`, your `client_id`, `redirect_uri`,
   `scope`, `code_challenge`, and `code_challenge_method=S256`.
2. Exchange the returned `code` at the token endpoint:
   `https://dev.overskill.com/oauth/token`
   with `grant_type=authorization_code` and your PKCE `code_verifier`.
3. Store the `access_token` (and `refresh_token`) and refresh via
   `grant_type=refresh_token` when the access token expires.

## Scopes

| Scope        | Grants                                         |
|--------------|------------------------------------------------|
| `read`       | Read access to apps and resources              |
| `write`      | Write access to apps and resources             |
| `apps:read`  | Read access to apps only                       |
| `apps:write` | Write access to apps only                      |

## Using the credential

Send the bearer token on every authenticated request:

```
Authorization: Bearer <access_token>
```

## Identity assertions

OverSkill verifies end-user email addresses through Google and GitHub
SSO. When a user authenticates via a provider that asserts the email is
verified, OverSkill treats that identity as **`verified_email`**. This
is the identity assertion exposed under
`agent_auth.identity_assertions.verified_email` in the OAuth
Authorization Server Metadata document. We make no claims we cannot
back: only `verified_email` and standard OAuth bearer identity.

## See also

- Developer docs: `https://dev.overskill.com/developers`
- Agent overview: `https://dev.overskill.com/agents`
- SKILL.md: `https://dev.overskill.com/SKILL.md`