# Build with AI coding agents

> Give an AI coding agent the OneiD documentation in a form it can read, and use ready-made prompts to add sign-in or protect an API.

Source: https://oltinid.com/docs/ai/build-with-ai/ · Section: AI agents · All OneiD documentation: https://oltinid.com/llms.txt

AI coding agents such as Claude Code, Cursor, GitHub Copilot and ChatGPT can add OneiD sign-in to an application or protect an API, as long as they work from the OneiD documentation rather than from general assumptions about identity providers. This page shows how to hand them the documentation and what they need from you.

## Give your agent the documentation

The OneiD documentation is published in forms that agents read well.

| Source | Address | Use it when |
|---|---|---|
| Index | `https://oltinid.com/llms.txt` | The agent should pick the pages it needs. |
| Full documentation | `https://oltinid.com/llms-full.txt` | The agent should read everything at once, in one file. |
| One page as Markdown | Add `.md` to the page address, without the trailing slash | You want to give the agent one specific page. |
| OneiD skill file | `https://oltinid.com/oneid-skill.md` | Your agent supports skill or rules files. |
| Connector specification | [Connector specification](https://oltinid.com/docs/ai/connector-specification/) | The agent builds a reusable integration for a framework or product. |

For example, the Markdown version of the sign-out guide is `https://oltinid.com/docs/guides/logout.md`.

Every documentation page also has a **Copy page** button. It copies the page as Markdown, so you can paste it into a chat. The **Open in AI** menu next to it starts a conversation about the page in Claude, ChatGPT, Microsoft Copilot, Perplexity, Grok or Mistral Le Chat, with the prompt already filled in. For Gemini it copies the prompt and opens Gemini for you to paste it. **Cursor** opens the prompt in the Cursor app, and **Copy prompt for a coding agent** gives you a prompt for Claude Code, GitHub Copilot, Windsurf, Codex or any other agent that works in your project.

### The OneiD skill file

`https://oltinid.com/oneid-skill.md` is a single Markdown file that agents can load as a skill or rules file, so that OneiD's rules are in front of the agent while it works. Load it the way your agent loads skills or rules, for example by saving it in the project's rules or instructions folder or by attaching it to the conversation.

### What is not available

> **Not supported:** There is no hosted documentation MCP server for OneiD and no AI assistant on oltinid.com. Use the files above.

## What the agent must ask you for

An agent cannot register applications in OneiD. An administrator registers each application, and the agent needs the results. Before it writes code, a good agent asks for:

- **The OneiD address**, for example `https://YOUR_ONEID`. The issuer is this address with a trailing slash.
- **The client ID** of the registered application.
- **The client type**: public (browser, mobile, desktop; no secret) or confidential (server-side; with a client secret).
- **The client secret**, for a confidential client. The agent should read it from configuration or a secret store, never write it into code.
- **The redirect URI**, exactly as registered, for example `https://app.example.com/callback`.
- **The post-logout redirect URI**, if the application signs users out.
- **The scopes** the client is allowed, including any API scopes.
- **For an API**: the scope or scopes each endpoint requires.

If you do not have these yet, ask your OneiD administrator. See [Register an application](https://oltinid.com/docs/get-started/register-an-application/).

## Prompt: add OneiD sign-in to an application

Copy this prompt, fill in the values in angle brackets, and give it to your agent together with the documentation.

```text
Add sign-in with OneiD to this application.

Read the OneiD documentation first:
- https://oltinid.com/llms-full.txt (all documentation), or at least
- https://oltinid.com/docs/ai/connector-specification.md
- https://oltinid.com/docs/guides/authorization-code-pkce.md
- https://oltinid.com/docs/guides/logout.md

My OneiD settings:
- OneiD address: <https://YOUR_ONEID>
- Client ID: <YOUR_CLIENT_ID>
- Client type: <public | confidential>
- Client secret: read it from the environment variable <ONEID_CLIENT_SECRET> (confidential only)
- Redirect URI (registered): <https://app.example.com/callback>
- Post-logout redirect URI (registered): <https://app.example.com/>
- Scopes: <openid profile email roles>

Requirements:
- Use the framework's maintained OpenID Connect library. Configure it from the discovery document.
- Authorization code flow with PKCE (S256), state and nonce.
- The issuer is the OneiD address with a trailing slash. Compare it exactly.
- Validate the ID token as the connector specification describes.
- Key users by iss + sub, never by email.
- Read roles from the "role" claim; it can be a string or an array.
- Sign-out: clear the local session, then redirect to the end-session endpoint with id_token_hint and post_logout_redirect_uri.
- Never log tokens or the client secret.
- Do not use features OneiD does not support (see the connector specification, section 16).

When you are done, list what you changed and walk the conformance checklist in section 17 of the connector specification.
```

## Prompt: protect an API with OneiD

```text
Protect this API with OneiD access tokens.

Read the OneiD documentation first:
- https://oltinid.com/docs/guides/protect-an-api.md
- https://oltinid.com/docs/ai/connector-specification.md (section 12)

My OneiD settings:
- OneiD address: <https://YOUR_ONEID>
- Required scopes: <GET /orders needs orders.read; POST /orders needs orders.write>
- Roles (optional): <DELETE /orders/{id} also needs the role OrderManager>

Requirements:
- Use a maintained JWT library for the framework.
- Get issuer and jwks_uri from the discovery document. Cache the JWKS and re-fetch on an unknown kid.
- Accept only RS256. Check iss exactly, with the trailing slash. Check exp with at most 60 seconds of clock skew.
- Do NOT require an aud claim; OneiD access tokens have none.
- Check the required scope in the space-separated "scope" claim on every endpoint.
- Return 401 with WWW-Authenticate: Bearer error="invalid_token" for bad tokens,
  and 403 with error="insufficient_scope" when the scope is missing.
- Never log tokens.

Add tests for: a valid token, an expired token, a wrong issuer, a token signed with an unknown key,
a missing scope, and a request without a token.
```

## Check the agent's work

Review what the agent produced before you ship it. In particular:

- The issuer contains the trailing slash and the code does not require `aud` on access tokens.
- PKCE uses `S256`.
- No client secret is in the code or in a committed file.
- No token is written to logs.
- The application handles `invalid_grant` on refresh by signing the user in again.

The [Security best practices](https://oltinid.com/docs/guides/security-best-practices/) checklist covers the rest.

## Learn more

- [Connector specification](https://oltinid.com/docs/ai/connector-specification/)
- [Quickstarts](https://oltinid.com/docs/quickstarts/)
- [Register an application](https://oltinid.com/docs/get-started/register-an-application/)
- [Security best practices](https://oltinid.com/docs/guides/security-best-practices/)