# Authentication at Rimble

This document tells automated clients and AI agents how authentication actually works
at Rimble, and how to obtain access.

**Summary: Rimble does not offer self-serve or automated agent registration.** API
credentials are issued to commercial partners by a human. An agent cannot provision its
own credentials here. If you are an agent acting for a user, the correct action is to
surface the contact route below to that user, not to attempt registration.

---

## 1. Rimble Raw Data API (the product API)

The public product API is the Rimble Raw Data API.

| Property | Value |
| --- | --- |
| Base URL | `https://rimbleanalytics.com` |
| Description | [`https://www.rimble.io/openapi.yaml`](https://www.rimble.io/openapi.yaml) (OpenAPI 3.0.3) |
| Documentation | [`https://www.rimble.io/docs`](https://www.rimble.io/docs) |
| Scheme | API key |
| Credential transport | `x-api-key` request header |
| Methods | `GET` only |
| How to obtain | Commercial agreement — contact `support@rimble.io` |

Example:

```http
GET /raw/lol/upcoming-matches/ HTTP/1.1
Host: rimbleanalytics.com
x-api-key: <your-issued-key>
```

All paths require a **trailing slash**. Prefer query parameters over calling a bare
collection endpoint, to keep responses manageable. Data feeds refresh hourly at
10 minutes past the hour.

This API does **not** use OAuth. There is no authorization endpoint, no token endpoint,
and no dynamic client registration for it.

---

## 2. `https://www.rimble.io/api/*` (internal tooling)

The `/api/*` namespace on this site is an internal operations proxy. It is not a
partner-facing product API and is not intended for third-party or agent integration.

| Property | Value |
| --- | --- |
| Resource identifier | `https://www.rimble.io/api` |
| Protected-resource metadata | [`/.well-known/oauth-protected-resource`](https://www.rimble.io/.well-known/oauth-protected-resource) |
| Authorization server | `https://accounts.google.com` (Google) |
| Credential transport | `Authorization: Bearer <Google ID token>` |
| Additional gate | The token's verified email must be on an internal allowlist |

Two things follow from this, and they are the reason a generic OAuth flow will not get
an agent in:

1. **Rimble is not the authorization server.** Tokens are issued by Google and verified
   against Rimble's Google client ID. Discover Google's endpoints at
   `https://accounts.google.com/.well-known/openid-configuration`. Rimble itself
   publishes **no** `/.well-known/openid-configuration` and no
   `/.well-known/oauth-authorization-server`, because it issues no tokens. Those paths
   return `404` deliberately.

2. **A valid Google token is necessary but not sufficient.** Access additionally
   requires the account's email to be on an internal allowlist. A correctly
   authenticated request from a non-allowlisted account receives `403`
   `{"error":"email_not_allowed"}`. RFC 9728 has no field to express this, which is why
   it is documented here.

Unauthenticated requests receive `401` with a `WWW-Authenticate: Bearer` challenge
carrying a `resource_metadata` parameter pointing back at this resource's metadata
document.

---

## 3. Machine-readable discovery

| Resource | Path |
| --- | --- |
| API catalog (RFC 9727) | [`/.well-known/api-catalog`](https://www.rimble.io/.well-known/api-catalog) |
| Protected resource metadata (RFC 9728) | [`/.well-known/oauth-protected-resource`](https://www.rimble.io/.well-known/oauth-protected-resource) |
| OpenAPI description | [`/openapi.yaml`](https://www.rimble.io/openapi.yaml) |
| AI plugin manifest | [`/.well-known/ai-plugin.json`](https://www.rimble.io/.well-known/ai-plugin.json) |
| Agent skills index | [`/.well-known/agent-skills/index.json`](https://www.rimble.io/.well-known/agent-skills/index.json) |
| Site summary for LLMs | [`/llms.txt`](https://www.rimble.io/llms.txt), [`/llms-full.txt`](https://www.rimble.io/llms-full.txt) |

## 4. Not offered

These are listed explicitly so agents stop probing for them:

- Dynamic client registration (RFC 7591) — not offered.
- OAuth authorization server metadata (RFC 8414) — not offered; Rimble issues no tokens.
- OpenID Connect discovery — not offered by Rimble; the upstream IdP is Google.
- MCP server — none is currently operated, so no server card is published.
- Self-serve API key provisioning — keys are issued under a commercial agreement.

## 5. Contact

- API access and commercial enquiries: `support@rimble.io`
- Terms of service: <https://www.rimble.io/terms>
- Privacy policy: <https://www.rimble.io/privacypolicy>