generated: '2026-08-26'
method: searched
source: https://www.rhombus.com/auth.md
secondary_sources:
- https://api-docs.rhombus.community/oauth-authentication
- https://api2.rhombussystems.com/.well-known/oauth-protected-resource
- https://auth.rhombussystems.com/oauth/.well-known/oauth-authorization-server
- openapi/rhombus-systems-openapi.json
note: >-
  Upgraded from derived to searched. The OpenAPI declares only ONE security scheme (ApiKeyAuth),
  but Rhombus publishes a full second method — OAuth 2.0 authorization code with PKCE — in a
  dedicated machine-readable auth guide and in its own agent card. The spec understates the auth
  surface; this artifact records what the provider actually supports.
anonymous_access: false
anonymous_statement: 'There is no anonymous access: every API call requires one of the two credentials.'
summary:
  types: [apiKey, oauth2]
  api_key_in: [header]
  methods: 2
hosts:
- host: api2.rhombussystems.com
  role: resource server (all API calls)
- host: console.rhombus.com
  role: interactive sign-in and OAuth authorization
- host: auth.rhombussystems.com
  role: OAuth token, refresh, revocation and client registration
- host: auth-web.rhombussystems.com
  role: declared OAuth issuer in the RFC 8414 metadata
schemes:
- name: ApiKeyAuth
  type: apiKey
  in: header
  parameter: x-auth-apikey
  companion_header:
    name: x-auth-scheme
    values: [api-token, partner-api-token]
    required: true
  description: >-
    Rhombus API key. Requires the x-auth-scheme companion header — a key alone is not a complete
    credential. api-token for standard auth, partner-api-token for partner/MSP auth.
  self_serve: true
  provisioning: https://console.rhombus.com/settings/api-management
  shown_once: true
  permission_model: >-
    A key INHERITS the permissions of the user who created it. There are no key-level scopes;
    least privilege is achieved by creating the key from a least-privileged user or role.
  recommended_for: agents, scripts, server-to-server integrations acting as one Rhombus account
  region_bound: true
  region_note: Keys are bound to their region — a US key will not work against api2.eu.rhombussystems.com.
  sources:
  - openapi/rhombus-systems-openapi.json
  - https://www.rhombus.com/auth.md
- name: OAuth2
  type: oauth2
  flow: authorization_code
  pkce: true
  pkce_methods: [S256]
  description: >-
    "Sign in with Rhombus" — OAuth 2.0 authorization code with PKCE, for third-party apps where
    Rhombus customers sign in to the developer's product. Gives per-user consent, refresh tokens
    and revocation.
  declared_in_openapi: false
  endpoints:
    authorization: https://console.rhombus.com/oauth/authorize
    token: https://auth.rhombussystems.com/oauth/token
    revocation: https://auth.rhombussystems.com/oauth/token/revoke
    registration: https://auth-web.rhombussystems.com/oauth/register
    issuer: https://auth-web.rhombussystems.com/
  grant_types_supported: [authorization_code, refresh_token]
  response_types_supported: [code]
  token_endpoint_auth_methods_supported: [client_secret_basic, client_secret_post, none]
  dynamic_client_registration: true
  usage_headers:
    x-auth-scheme: api-oauth-token
    x-auth-access-token: ACCESS_TOKEN
  token_exchange_header:
    x-auth-scheme: web2
  access_token_lifetime_sec: 3600
  client_provisioning:
    operationId: submitApplication
    path: /api/oauth/submitApplication
    authenticated_with: an API key
    returns: [clientId, clientSecret]
    related_operations: [getAllApplicationsForOrg, getApplicationByClientId, updateApplication, deleteApplication]
    secret_shown_once: true
    review_required: >-
      Production apps distributed to other organizations require Rhombus review, started in the
      developer community.
  recommended_for: third-party applications acting on behalf of a Rhombus user
  sources:
  - https://www.rhombus.com/auth.md
  - https://api-docs.rhombus.community/oauth-authentication
  - https://auth.rhombussystems.com/oauth/.well-known/oauth-authorization-server
scopes:
  published: false
  scope_count: 0
  note: >-
    Rhombus publishes NO OAuth scope vocabulary. The RFC 8414 metadata omits scopes_supported
    entirely and the provider's own agent card declares the oauth2 flow with an empty scopes
    object. Authorization is therefore role-derived (the consenting user's permissions), not
    scope-derived, and an agent cannot request or reason about least-privilege at the token
    level. No scopes/ artifact is emitted because there is no scope surface to record.
  role_model:
    operations:
    - getPermissionGroups
    - getPartnerPermissionGroups
    - getUsersInOrg
    note: Permissions are managed as org permission groups (Permission Webservice, 10 operations).
discovery:
  rfc9728:
    url: https://api2.rhombussystems.com/.well-known/oauth-protected-resource
    status: 200
    anonymous: true
    resource: https://api2.rhombussystems.com
    authorization_servers: [https://auth-web.rhombussystems.com/]
    bearer_methods_supported: [header]
  rfc8414:
    url: https://auth.rhombussystems.com/oauth/.well-known/oauth-authorization-server
    status: 200
    anonymous: true
  challenge:
    status: 401
    header: 'WWW-Authenticate: Bearer resource_metadata="https://api2.rhombussystems.com/.well-known/oauth-protected-resource"'
    note: >-
      The entire discovery chain is reachable from ONE unauthenticated probe — a 401 on any
      endpoint hands back the RFC 9728 URL, which names the authorization server, whose RFC 8414
      document names every endpoint. This is a genuinely agent-friendly bootstrap.
  openid_connect:
    supported: false
    probe: https://www.rhombus.com/.well-known/openid-configuration
    status: 404
mtls:
  supported: true
  note: >-
    The Rhombus Console offers certificate-based API keys in addition to token-based ones. The
    published OpenAPI does not model a mutualTLS security scheme, and the AsyncAPI states
    explicitly that certificate (mTLS) keys are NOT supported by the WebSocket service — only
    token-based keys are.
  source: asyncapi/rhombus-systems-console-websocket-asyncapi.json
enterprise_sso:
  saml2: true
  operations: [getSAMLSettings, getSAMLSettingsV2, updateSAMLSettings, updateSAMLSettingsV2]
  scim: true
  scim_operations: [setupSCIMAccessForOrg, findSCIMSettingsForOrg, updateSCIMSettingsForOrg, getScimDisplayInfo, revokeSCIMAccessForOrg]
  idps_documented: [Okta, Azure AD, Google Workspace, OneLogin]
  documentation: https://api-docs.rhombus.community/implementations/saml-sso-provisioning
partner_auth:
  scheme_value: partner-api-token
  org_scoping_header: x-auth-org
  note: MSPs and resellers authenticate with a partner key and scope calls to a managed client org.
  documentation: https://api-docs.rhombus.community/partner-api-calls
gaps:
- The OpenAPI declares only ApiKeyAuth; the OAuth 2.0 method it fully documents elsewhere is absent from the contract.
- No OAuth scope vocabulary, so no least-privilege token model.
- No key-level scoping — an API key carries its creator's full permissions.
- No OIDC discovery document, so no standard identity-claim surface despite OAuth support.