Skip to main content

COG-3: Authentication

Status:      Draft
Version:     2.0
Created:     2025-09-24
Updated:     2026-01-28
Authors:     Mike Anderson

Purpose​

Authentication ensures the integrity, security, and controlled access to assets and operations on the grid. This document specifies authentication mechanisms for venues, enabling secure and flexible access control while maintaining venue operators' autonomy over access policies.

Authentication is managed at a per-venue level, allowing venue operators to define and enforce access policies tailored to their specific requirements.

Authentication mechanisms are built on commonly available web standards and, where appropriate, make use of decentralised facilities supported by Convex lattice technology.

Principles​

  • Venue autonomy — Each venue operator decides which authentication mechanisms to support and what privileges to grant.
  • Layered security — Multiple mechanisms MAY be supported simultaneously, allowing clients to use whichever is appropriate.
  • Standards-based — All mechanisms use established web and cryptographic standards.
  • Decentralisation-ready — Ed25519 key-based authentication ties into the broader Convex identity model without requiring centralised credential stores.

Specification​

1. Public Access (No Authentication)​

Venues MAY provide open, public access to grid operations and assets, enabling public services or sharing open-source capabilities without requiring prior authorisation.

Public access is the simplest mode and is appropriate for open data, demo services, and community resources.

Venues SHOULD NOT allow unauthorised users to consume excessive resources.

Venues SHOULD implement rate limiting on public endpoints, e.g. via a reverse proxy or application-level throttling.

2. Bearer Token (API Key)​

Venues MAY offer authorisation using bearer tokens (commonly referred to as API keys).

The token MUST be passed by the client with every HTTPS request using the standard Authorization header:

Authorization: Bearer <token>

If the venue offers bearer-token authorisation, it has complete control over what privileges it grants to clients using any particular token. Token provisioning is out of scope for this specification and is managed by the venue operator (e.g. via a management portal, CLI, or out-of-band exchange).

Security considerations​

  • Tokens MUST be treated as secrets and MUST NOT be logged, committed to version control, or transmitted over unencrypted channels.
  • Venues SHOULD support token revocation.
  • Venues SHOULD enforce token expiry where appropriate.

3. HTTP Basic Authentication​

Venues MAY support HTTP Basic authentication as defined in RFC 7617.

Credentials are transmitted as a Base64-encoded username:password pair in the Authorization header:

Authorization: Basic <base64(username:password)>

Basic authentication MUST only be used over HTTPS to protect credentials in transit.

This mechanism is suitable for simple setups, internal tooling, or development environments where a lightweight credential model is sufficient.

4. OAuth 2.0​

Venues MAY allow authentication using OAuth 2.0 with PKCE (RFC 7636).

OAuth enables delegated authorisation, allowing users to authenticate via an external identity provider (e.g. Google, GitHub, or a corporate IdP) without sharing their credentials with the venue.

Flow overview​

  1. Client initiates an authorisation request to the venue's OAuth endpoint.
  2. Venue redirects the client to the identity provider for authentication.
  3. On successful authentication, the identity provider returns an authorisation code to the venue callback.
  4. The venue exchanges the code for an access token.
  5. The client uses the access token as a bearer token for subsequent API requests.

Requirements​

  • Venues implementing OAuth MUST use PKCE to mitigate authorisation code interception attacks.
  • Access tokens SHOULD be short-lived; refresh tokens MAY be issued for long-lived sessions.
  • Venues MUST validate tokens on every request.

5. Ed25519 Key-Pair Signing​

Venues MAY authenticate clients using Ed25519 digital signatures as proof of key possession. This mechanism aligns with the Convex identity model, where accounts are identified by Ed25519 public keys.

Ed25519 signing provides strong, decentralised authentication without shared secrets. The client proves possession of a private key by signing a challenge or request payload; the venue verifies the signature against the client's known public key.

Flow overview​

  1. Client presents its Ed25519 public key (or a DID derived from it) to identify itself.
  2. The venue issues a challenge (a unique nonce or includes the request payload).
  3. The client signs the challenge with its private key and includes the signature in the request.
  4. The venue verifies the signature against the claimed public key.

Header format​

The signature and public key SHOULD be conveyed via HTTP headers. The exact header format is to be finalised, but the following structure is anticipated:

Authorization: Ed25519 <base64(public-key)>:<base64(signature)>

Or using a structured challenge-response scheme where the venue provides a nonce:

X-Covia-Signature: <base64(signature)>
X-Covia-Public-Key: <base64(public-key)>
X-Covia-Nonce: <nonce>

Security considerations​

  • Private keys MUST NOT leave the client and MUST NOT be transmitted over the network.
  • Nonces MUST be single-use to prevent replay attacks.
  • The public key MAY be registered with the venue in advance, or MAY be resolved via a DID document.
  • This mechanism integrates naturally with Convex account keys, enabling on-chain identity verification.

Client SDK Support​

The Covia SDKs provide a generic authentication interface that supports all mechanisms described above.

MechanismPython SDKJava SDK
Public (no auth)DefaultDefault
Bearer tokenBearerAuth(token)Supported
HTTP BasicBasicAuth(user, pass)Supported
OAuth 2.0PlannedSupported
Ed25519 signingPlannedPlanned

Python SDK example​

from covia import Grid
from covia.auth import BearerAuth, BasicAuth

# Public access (no auth)
venue = Grid.connect("https://venue.covia.ai")

# Bearer token
venue = Grid.connect("https://venue.covia.ai", auth=BearerAuth("my-token"))

# HTTP Basic
venue = Grid.connect("https://venue.covia.ai", auth=BasicAuth("user", "pass"))

Custom authentication providers can be implemented by subclassing covia.auth.Auth:

from covia.auth import Auth

class ApiKeyAuth(Auth):
    def __init__(self, key: str) -> None:
        self._key = key

    def apply(self, headers: dict[str, str]) -> None:
        headers["X-Api-Key"] = self._key

Venue Discovery​

Venues SHOULD advertise their supported authentication mechanisms via the A2A agent card (/.well-known/agent-card.json) using the securityScheme field. This allows clients to discover the required authentication method before making API calls.

References​