Authentication Schemes

Configure Bearer tokens, API keys, OAuth2 flows, and custom headers for GraphQL API authentication.

February 4, 2026

NeoArc Studio supports four authentication scheme types for GraphQL APIs. This guide provides detailed configuration for each type.

Bearer Token Authentication

Bearer authentication transmits a token in the Authorization header. This is the most common authentication method for user-facing GraphQL APIs.

Property	Required	Description
id	Yes	Unique identifier for the scheme
type	Yes	Must be "bearer"
description	No	Explanation of the authentication method
bearerFormat	No	Token format hint (e.g., "JWT", "opaque")
headerName	No	Custom header name (default: "Authorization")

{
  "id": "bearerAuth",
  "type": "bearer",
  "description": "JWT token obtained from the authentication endpoint. Tokens expire after 1 hour and must be refreshed using the refresh token.",
  "bearerFormat": "JWT"
}

Custom Header Name

Some APIs use a different header name for bearer tokens:

{
  "id": "customBearer",
  "type": "bearer",
  "description": "Authentication token in X-Auth-Token header",
  "bearerFormat": "JWT",
  "headerName": "X-Auth-Token"
}

API Key Authentication

API key authentication uses a secret key passed in a header or query parameter. Common for server-to-server communication and public APIs with rate limiting.

Property	Required	Description
id	Yes	Unique identifier for the scheme
type	Yes	Must be "apiKey"
name	Yes	Header or parameter name (e.g., "X-API-Key")
in	Yes	Location: "header" or "query"
description	No	Explanation of the authentication method

{
  "id": "apiKeyAuth",
  "type": "apiKey",
  "name": "X-API-Key",
  "in": "header",
  "description": "API key for service accounts. Request keys through the developer portal."
}

{
  "id": "queryKeyAuth",
  "type": "apiKey",
  "name": "api_key",
  "in": "query",
  "description": "API key passed as query parameter. Note: Header placement is preferred for security."
}

OAuth2 Authentication

OAuth2 provides delegated authorisation with scope-based access control. NeoArc supports two OAuth2 flows:

Complete OAuth2 Example

{
  "id": "oauth2",
  "type": "oauth2",
  "description": "OAuth2 authentication supporting user and service authentication",
  "flows": {
    "authorizationCode": {
      "authorizationUrl": "https://auth.example.com/authorize",
      "tokenUrl": "https://auth.example.com/token",
      "refreshUrl": "https://auth.example.com/refresh",
      "scopes": {
        "users:read": "Read user profiles and preferences",
        "users:write": "Update user profiles",
        "orders:read": "View order history and status",
        "orders:write": "Create and modify orders",
        "admin": "Administrative access (requires approval)"
      }
    },
    "clientCredentials": {
      "tokenUrl": "https://auth.example.com/token",
      "scopes": {
        "service:sync": "Synchronise data between services",
        "service:reports": "Generate aggregate reports"
      }
    }
  }
}

Scope Naming Conventions

Use consistent scope naming for clarity:

Pattern	Example	Meaning
resource:action	users:read	Read access to users
resource:action	orders:write	Write access to orders
admin:resource	admin:users	Admin access to users
service:function	service:sync	Service-level sync capability

Custom Headers Authentication

Custom header authentication handles non-standard authentication requiring specific header combinations.

Property	Required	Description
id	Yes	Unique identifier for the scheme
type	Yes	Must be "customHeader"
headers	Yes	Array of required headers
description	No	Explanation of the authentication method

{
  "id": "hmacAuth",
  "type": "customHeader",
  "description": "HMAC signature authentication requiring timestamp and signature headers",
  "headers": [
    {
      "name": "X-Timestamp",
      "description": "Unix timestamp of the request (must be within 5 minutes of server time)"
    },
    {
      "name": "X-Signature",
      "description": "HMAC-SHA256 signature of the request body using your API secret"
    },
    {
      "name": "X-Client-ID",
      "description": "Your client identifier"
    }
  ]
}

Combining Schemes

The OR-of-ANDs structure allows combining multiple schemes. Common patterns: