API Authentication

Defender APIs use short-lived JWT tokens for authentication, which can be negotiated via SRP protocol. We suggest using the Amazon Cognito User Pool SDK to negotiate the token.

The JWT token will expire after 60 minutes. If your code requires sessions longer than 60 minutes, consider recreating the JWT token, or using a refresh token.

If you are using a defender-client npm package all authentication and renewal is automatically handled for you, just by providing the API key and secret.

Making Authenticated Requests

Once you get a JWT Token you can make requests to the Defender API. A request requires an API key, a JWT Token, optionally a payload, and an API URL. Set $KEY, $TOKEN to the values of API key and JWT Token acquired before. $END_POINT can be either txs or sign.


curl \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "X-Api-Key: $KEY" \
  -H "Authorization: Bearer $TOKEN" \

Using Python

The official AWS SDK for python doesn’t support SRP authentication, but it is possible to retrieve a JWT token using the warrant library.

import boto3
from warrant.aws_srp import AWSSRP

client = boto3.client('cognito-idp', region_name='us-west-2')
aws = AWSSRP(username='API_KEY', password='API_SECRET', pool_id='POOL_ID', client_id='CLIENT_ID', client=client)
tokens = aws.authenticate_user()
print('Access Token', tokens['AuthenticationResult']['AccessToken'])

Replace the API_KEY and API_SECRET with your api key and secret, and POOL_ID and CLIENT_ID with the user pool IDs for the API you are accessing.

APIs Settings

These settings are automatically managed by the defender-client packages, but if you are manually handling authentication, you will need them to configure the SRP protocol.

  • The Admin API is at host defender-api.openzeppelin.com, and authentication is served by the user pool us-west-2_94f3puJWv and client 40e58hbc7pktmnp9i26hh5nsav. You will need Team API Keys to authenticate, which can be found in the top-right menu in Defender.

  • The Relayer API is at host api.defender.openzeppelin.com, and authentication is served by the user pool us-west-2_iLmIggsiy and client 1bpd19lcr33qvg5cr3oi79rdap. You will need to generate Relayer API keys to authenticate, which are created in each Relayer’s page.