Agent Authentication (auth.md)

This document describes how AI agents can authenticate and interact with Cheers Location APIs.

Agent Registration

To access protected Cheers Location APIs, agents must register and obtain credentials.

Registration Process

1. Register your agent: POST your agent metadata to our registration endpoint
2. Receive credentials: Obtain client ID, client secret, and configuration
3. Authenticate: Use OAuth 2.0 client credentials flow or other supported methods

Registration Endpoint

POST https://cheerslocation.fr/agents/register

Required Agent Metadata

• agent_name: Human-readable name of your agent
• agent_uri: Unique identifier/URL for your agent
• agent_type: Type of agent (crawler, assistant, automation, etc.)
• purpose: Description of what your agent does
• contact_email: Email for API support
• redirect_uris: Array of callback URLs for OAuth flows

Authentication Methods

OAuth 2.0 Client Credentials Flow (for server-to-server)

# Request access token
POST https://cheerslocation.fr/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&scope=read:catalogue

OAuth 2.0 Authorization Code Flow (for user-delegated access)

# Step 1: Redirect user to authorization endpoint
GET https://cheerslocation.fr/oauth/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  scope=read:catalogue read:quotes&
  state=RANDOM_STRING

# Step 2: Exchange code for token
POST https://cheerslocation.fr/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
code=AUTHORIZATION_CODE&
redirect_uri=YOUR_REDIRECT_URI

Supported Scopes

Token Management

Token Revocation

POST https://cheerslocation.fr/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=ACCESS_TOKEN_OR_REFRESH_TOKEN&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

Token Introspection

POST https://cheerslocation.fr/oauth/introspect
Content-Type: application/x-www-form-urlencoded

token=ACCESS_TOKEN&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

Discovery Endpoints

• OAuth Configuration: https://cheerslocation.fr/.well-known/openid-configuration
• Protected Resource Metadata: https://cheerslocation.fr/.well-known/oauth-protected-resource
• JWKS: https://cheerslocation.fr/.well-known/jwks.json

Rate Limits

• 100 requests per minute for authenticated agents
• 10 requests per minute for unauthenticated access
• Burst limits may apply

Terms of Service

By accessing our APIs, you agree to:

• Not exceed rate limits
• Cache responses appropriately
• Respect our data privacy policies
• Not use the API for competitive analysis
• Attribute Cheers Location when displaying our data

Support

For API support and agent registration issues, contact:

• Email: api-support@cheerslocation.fr
• Documentation: https://cheerslocation.fr/docs/api/
• Status Page: https://cheerslocation.fr/api/health

Security

• All API endpoints use HTTPS
• Tokens are short-lived (1 hour default)
• Use refresh tokens for long-running sessions
• Report security issues to: security@cheerslocation.fr