GraphQL Security

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

February 4, 2026

GraphQL APIs require strong authentication and authorisation. NeoArc Studio supports four authentication scheme types and flexible requirement configuration using an OR-of-ANDs structure.

Authentication Scheme Types

NeoArc supports four authentication scheme types:

Scheme Configuration

Authentication schemes are defined at the API level and referenced by operations:

{
  "authSchemes": [
    {
      "id": "bearerAuth",
      "type": "bearer",
      "description": "JWT token authentication",
      "bearerFormat": "JWT"
    },
    {
      "id": "apiKeyAuth",
      "type": "apiKey",
      "name": "X-API-Key",
      "in": "header",
      "description": "API key for service accounts"
    }
  ]
}

OR-of-ANDs Requirements Structure

Authentication requirements use a flexible OR-of-ANDs structure that handles complex authentication scenarios:

{
  "defaultAuthRequirements": [
    [
      { "schemeId": "bearerAuth" }
    ],
    [
      { "schemeId": "apiKeyAuth" },
      { "schemeId": "signatureAuth" }
    ]
  ]
}

In this example, clients can authenticate using either:

A Bearer token alone, OR
Both an API key AND a signature header together

Default vs Operation-Level Security

Set API-level defaults for the most common case, then override at the operation level for exceptions:

OAuth2 Scopes

OAuth2 schemes support scope-based access control. Define scopes when configuring the OAuth2 scheme:

{
  "id": "oauth2",
  "type": "oauth2",
  "description": "OAuth2 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",
        "users:write": "Modify user profiles",
        "orders:read": "View orders",
        "orders:write": "Create and modify orders",
        "admin:users": "Administrative user management"
      }
    }
  }
}

When requiring OAuth2 authentication, specify which scopes the operation needs:

{
  "authRequirements": [
    [
      {
        "schemeId": "oauth2",
        "scopes": ["users:read", "orders:read"]
      }
    ]
  ]
}

Security Editor Interface

The Security tab in the API editor provides:

Auth Schemes List - Add, edit, and remove authentication schemes
Scheme Type Selector - Choose from Bearer, API Key, OAuth2, or Custom Headers
OAuth2 Flow Configuration - Configure Authorization Code and Client Credentials flows
Scope Management - Define and describe available scopes
Default Requirements - Configure API-level authentication defaults

Subscription Authentication

WebSocket-based subscriptions handle authentication differently:

Token typically passed during connection initialisation
Connection-level auth may apply to all subscriptions on that connection
Some implementations require per-subscription authentication

Document the subscription authentication flow in your API description.