Adverity Authentication

generated: '2026-08-13'
method: searched
source: https://docs.adverity.com/guides/management-api/authorizing-to-management-api.html
docs: https://docs.adverity.com/guides/management-api/authorizing-to-management-api.html
summary:
  types: [apiKey, oauth2]
  api_key_in: [header]
  oauth2_flows: [authorizationCode]
  note: >-
    The Adverity Management API uses long-lived API-key (token) authentication in the
    Authorization header — there is no OAuth2 on the Management API itself. OAuth2 appears in
    two other places: the remote MCP server runs its own OAuth 2.0 authorization server
    (authorization code + refresh, PKCE S256, dynamic client registration) in front of the
    same MAPI key, and OAuth is used downstream when Adverity authorizes to connected data
    sources (Google Ads, Facebook Ads, LinkedIn Ads) on the customer's behalf.
schemes:
- name: ManagementApiToken
  type: apiKey
  in: header
  parameter: Authorization
  format: 'Token {{KEY}}'
  description: >-
    API keys generated programmatically via POST https://{{INSTANCE}}/api/auth/token/
    (username + password, application/x-www-form-urlencoded). The response returns
    {username, token, expires_in} with expires_in null — the token does not expire and is
    only rotated when the account password is deliberately changed (profile settings,
    password reset, or an administrator reset). Adverity recommends a dedicated service
    account for long-lived integrations. These keys inherit the user's permissions and
    CANNOT call the user-management endpoints.
  sources: [docs]
- name: ManagementApiBearer
  type: apiKey
  in: header
  parameter: Authorization
  format: 'Bearer {{KEY}}'
  description: >-
    API keys generated in the Adverity UI (Administration > Management API keys). Assigned
    to a single workspace and valid for that workspace and its children. Maximum 5 keys per
    workspace; creation requires Administrator permissions in the root workspace. Keys do
    not expire, are shown exactly once at creation, carry per-resource scopes set to No
    access / Read-only / Write, and are the only keys that may call user-management
    endpoints.
  scopes_ref: scopes/adverity-scopes.yml
  sources: [docs]
- name: AdverityMcpOAuth
  type: oauth2
  flow: authorizationCode
  authorizationUrl: https://mcp.eu.adverity.com/authorize
  tokenUrl: https://mcp.eu.adverity.com/token
  registrationUrl: https://mcp.eu.adverity.com/register
  pkce: S256
  grant_types: [authorization_code, refresh_token]
  token_endpoint_auth_methods: [client_secret_post, client_secret_basic]
  description: >-
    Guards the remote MCP endpoint https://mcp.eu.adverity.com/mcp. The MCP client registers
    dynamically and runs an authorization-code flow; at Adverity's sign-in page the user
    supplies their Instance URL and MAPI key, so the agent's effective authority is exactly
    that key's scopes. Since release 2026.30 the server introspects the underlying API key
    on token refresh, so a revoked or rotated key invalidates the agent session immediately.
  scopes_supported: []
  sources: [https://mcp.eu.adverity.com/.well-known/oauth-authorization-server, https://docs.adverity.com/guides/mcp/mcp-setup.html]
  probed: '2026-08-13'
key_lifecycle:
  create_programmatic: POST /api/auth/token/
  create_ui: Administration > Management API keys (max 5 per workspace)
  rotate: POST /api/v1/auth/keys/current/rotate/
  introspect: GET /api/v1/auth/keys/introspect/
  introspect_note: >-
    Added 2026.30; unauthenticated route, IP-rate-limited. Returns active status and key
    details so a caller can verify key validity before use.
  revoke: Administration > Management API keys
  expiry: none
  displayed_once: true
downstream_oauth:
  note: >-
    Adverity holds OAuth credentials for the customer's connected marketing platforms
    (authorizations). Those are managed through /api/connection-types/{type_id}/connections/
    and the manage_authorization MCP tool, including account-level collection permissions and
    a grant-all flag. Updating permissions is a full replacement.
related:
- scopes/adverity-scopes.yml
- conventions/adverity-conventions.yml
- mcp/adverity-mcp.yml
- well-known/adverity-oauth-authorization-server.json