How do I add auth instructions and example calls to my docs?

A simple, effective pattern is to add an “Authentication” section near the top of your docs, then include copy-paste example requests for each endpoint.

1) Add a clear auth section

Include:

• Auth type: API key, bearer token, OAuth, etc.
• Where to send it: header/query param/cookie
• How to get it: link to dashboard or token creation page
• Required scopes/permissions if applicable

Example

## Authentication

This API uses Bearer token auth.

Send your token in the `Authorization` header:

Authorization: Bearer YOUR_API_TOKEN

You can create or manage tokens in your account settings.

2) Show a basic authenticated request

Give a minimal example that users can paste and run.

cURL

curl https://api.example.com/v1/projects \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

JavaScript

const res = await fetch("https://api.example.com/v1/projects", {
  headers: {
    Authorization: `Bearer ${process.env.API_TOKEN}`,
    "Content-Type": "application/json",
  },
});

const data = await res.json();
console.log(data);

3) Put example calls under each endpoint

For every endpoint, include:

• method + path
• short description
• required auth
• request example
• response example
• common errors

Example endpoint block

## List projects

`GET /v1/projects`

Requires authentication.

### Example request
```bash
curl https://api.example.com/v1/projects \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example response

{
  "data": [
    { "id": "proj_123", "name": "Website redesign" }
  ]
}

## 4) Make placeholders obvious
Use clear placeholders like:

- `YOUR_API_TOKEN`
- `YOUR_ACCOUNT_ID`
- `YOUR_ORG_ID`

This reduces confusion and copy/paste mistakes.

## 5) Document errors and troubleshooting
Common auth issues should be explained:

- `401 Unauthorized` — missing or invalid token
- `403 Forbidden` — token valid, but lacks permissions
- token expired / revoked
- wrong environment token used

### Example
```md
### Authentication errors

- `401 Unauthorized`: Your token is missing or invalid.
- `403 Forbidden`: Your token does not have access to this resource.

6) If possible, use tabs for multiple languages

For example:

• cURL
• JavaScript
• Python
• Go

This helps users quickly find a format they can use.

---

If you want, I can also give you:

1. a docs template you can paste into Markdown, or
2. a version tailored for OpenAPI/Swagger, Docusaurus, or ReadMe.com.