Authentication & Agent Credentials
Browser sign-in for interactive sessions; Agent Credentials exchanged for access tokens for headless use; scopes and rotation.
One identity model, two ways to obtain a token. Interactive sessions sign in through the browser; headless and CI workloads use an organization agent credential with the OAuth client-credentials flow. Either way the gateway receives a bearer access token, and Mediafier resolves who you are — and which organization you act for — on the server.
Choosing a path
Connecting an MCP-aware agent or IDE
Browser sign-in (most clients self-register)
Headless scripts, CI, or a server
Organization agent credential (client credentials → bearer token)
You never set an organization or tenant header on a request. Org context is derived from your token.
Interactive sign-in
Most agent and IDE clients handle sign-in themselves: they register with the gateway and open a browser sign-in the first time you connect. There is no credential to paste, and the client refreshes the session for you.
Headless: Agent Credentials
For automation, CI, or a server with no browser, create an organization agent credential. It is an OAuth client credential (a client ID and a secret), not a gateway token: exchange it for a bearer access token with the OAuth client-credentials flow, then present that token. The Agent Card at https://mcp.mediafier.ai/.well-known/agent.json publishes a machine_credentials block with the token endpoint, the audience to request, and the client authentication method — that block, not the interactive authorization-server metadata, is the contract for this exchange.
Create an Agent Credential
An organization admin creates one in the Mediafier app under Settings → Organization → Agent Credentials (app.mediafier.ai/settings/org/api-keys): give it a label, the scopes it needs, and an expiry.
The secret is shown once, at creation time, and is never retrievable afterward. Copy it into your secret manager immediately. Listing keys shows metadata only (label, scopes, created, expires, last used, status) — never the secret.
Exchange it for an access token
This is a standard OAuth client-credentials request, form-encoded (client_secret_post). Read the token endpoint and audience from the Agent Card rather than hard-coding them, and keep the client ID and secret in environment variables from your secret manager:
The response carries access_token, token_type (Bearer) and expires_in (seconds). Reuse the token until it expires — request a new one shortly before expires_in runs out, not once per call; token requests are rate-limited.
Present the token
Send the access token as the bearer on every MCP request:
For example, list the tools your organization can call:
To use the token from your own TypeScript or Python code, see MCP Access.
The credential secret itself belongs in your secret manager only; the gateway does not accept it directly — only the access token.
Rotate and revoke
On the same Agent Credentials page:
Regenerate issues a new secret and keeps the old one working for a short grace window, so you can cut over without downtime.
Revoke disables a credential immediately.
The list shows metadata only; a secret is shown solely on creation and on regeneration, and only once.
Scopes and least privilege
Grant a key only the scopes it needs. A key scoped to read-only discovery cannot invoke tools; a key scoped for a single workload should not carry broad access. Narrow scopes limit blast radius if a key leaks.
What stays server-side
Identity is verified on every call.
Organization context is derived from your token — never trusted from a client header.
Authorization, rate limiting, billing, and audit run before any tool executes.
If a call is rejected, the response carries a trace identifier so support can correlate it.
Next steps
Getting Started — connect, sign in, first call.
MCP Access — setup for a specific client.
Last updated