AVA SDK Authentication

This page documents the authentication mechanisms in the AVA SDK JS, explaining how to authenticate with the Ava Protocol's AVS.

This page documents the authentication mechanisms in the AVA SDK JS, explaining how to authenticate with the Ava Protocol's Actively Validated Service (AVS) to access workflow management features. For information about the Client interface that uses these authentication methods, see Client Interface.

Overview#

The AVA SDK requires authentication to interact with AVS services. All operations except the initial authentication calls require a valid authentication key (auth key). The SDK supports two authentication methods:

  1. Signature-based Authentication: Uses a cryptographic signature from an Externally Owned Account (EOA) wallet.
  2. API Key Authentication: Uses a pre-provisioned API key for authentication.

Sources:

Authentication Methods#

Signature-based Authentication#

Signature-based authentication uses a cryptographic signature from an EOA wallet to verify identity. This is the most common authentication method for blockchain applications.

The signature is created by signing a message containing the authentication parameters with the private key of the wallet. The AVS service verifies the signature against the provided address.

Sources:

API Key Authentication#

API key authentication provides a way to authenticate without requiring an EOA signature, useful for server-side applications or automated processes.

The API key must be previously provisioned through the Ava Protocol service.

Sources:

Authentication Request Structure#

Both authentication methods share similar parameters:

ParameterTypeDescription
chainIdnumberThe blockchain network ID
addressstringThe EOA wallet address
issuedAtDateWhen the authentication request was created
expiredAtDateWhen the authentication request should expire
signature/apiKeystringThe signature or API key for authentication

Sources:

Authentication Flow in Detail#

Sources:

Using the Authentication Key#

Auth Key Structure#

The auth key returned by the authentication methods is a JWT (JSON Web Token) with the following structure:

  1. Header: Contains the algorithm and token type

  2. Payload: Contains claims about the identity and token validity

    • iss: Issuer ("AvaProtocol")
    • sub: Subject (EOA address for signature auth)
    • exp: Expiration timestamp

  3. Signature: Cryptographic signature from the AVS

Sources:

Setting the Auth Key in the Client#

After successful authentication, you can store the auth key in the client for subsequent requests:

Sources:

Using Auth Key in Individual Requests#

You can also provide an auth key for individual requests through the options parameter:

This is useful when you need to use different auth keys for different operations or when you don't want to store the auth key in the client.

Sources:

Auth Key Validation#

The SDK includes a method to check if an auth key is valid by decoding the JWT token and checking the expiration time:

This method does not verify the signature of the JWT, only checks if the token has expired.

Sources:

Error Handling#

Unauthenticated requests will fail with an error message containing "unauthenticated". This happens when:

  1. No auth key is provided (neither stored in the client nor passed in the options)
  2. The provided auth key is invalid or expired

Sources:

Best Practices#

  1. Auth Key Management: Store the auth key securely and don't expose it in client-side code.
  2. Key Rotation: Regularly refresh your auth key to minimize security risks.
  3. Error Handling: Implement proper error handling to catch authentication errors and re-authenticate when needed.
  4. Request Options: When working with multiple users or identities, use request-specific auth keys rather than storing them in the client.

Sources:

Authentication Code Example#

Here's a complete example showing how to authenticate with a signature and make an authenticated request:

Sources: