Logo
NeoArc Studio

Authentication Schemes

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

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.

{
  "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.

{
  "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:

Custom Headers Authentication

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

{
  "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:

Related Content