Skip to main content
Version: Next

Stellar Authentication for Contract Accounts (SEP-45)

Overview​

SEP-45 (Stellar Web Authentication for Contract Accounts) enables smart wallet applications to create authenticated sessions with Stellar anchors by proving control over a contract account (C...). Once authenticated, wallets receive a JSON Web Token (JWT) that they use in subsequent requests to the anchor's standardized services.

For the complete specification, see SEP-0045: Stellar Web Authentication for Contract Accounts.

The Anchor Platform implements SEP-45 with support for:

  • Challenge/Response Flow: GET /sep45/auth to request authorization entries, POST /sep45/auth to validate and receive a JWT
  • Contract Account Authentication: Support for contract accounts (C...) using Soroban authorization entries
  • Transaction Simulation: Automatic simulation of transactions to verify authorization entries
  • Multiple Home Domains: Support for multiple domains and wildcard patterns
info

SEP-45 vs SEP-10: SEP-45 does not replace SEP-10. SEP-45 supports contract accounts (C...), while SEP-10 supports classic accounts (G...) and muxed accounts (M...). Services wishing to support all account types should implement both SEPs.

Typical Authentication Flow​

  1. The Client requests a unique challenge from the Server
  2. The Client verifies and signs the challenge
  3. The Client submits the signed challenge to the Server
  4. The Server verifies the challenge and responds with a JWT session token

An implementation of the SEP-45 contract is provided in the Anchor Platform repository. An instance of this contract is deployed at CD3LA6RKF5D2FN2R2L57MWXLBRSEWWENE74YBEFZSSGNJRJGICFGQXMX on testnet.

Enable SEP-45​

SEP-45 requires integration with Stellar RPC to simulate transactions. The Anchor Platform can connect to the Stellar RPC server of your choice. You can use a public Stellar RPC provider, or you can run your own. A list of public providers can be found here.

To enable SEP-45, set the following environment variables in your dev.env file.

# dev.env
STELLAR_NETWORK_TYPE=rpc
STELLAR_NETWORK_RPC_URL=https://soroban-testnet.stellar.org
SEP45_ENABLED=true
SEP45_HOME_DOMAINS=localhost:8080
SEP45_WEB_AUTH_CONTRACT_ID="CD3LA6RKF5D2FN2R2L57MWXLBRSEWWENE74YBEFZSSGNJRJGICFGQXMX"
SECRET_SEP10_SIGNING_SEED="a Stellar private key"
SECRET_SEP45_JWT_SECRET="a secret encryption key"

Required Configuration (If Enabled)​

VariableDefaultDescription
STELLAR_NETWORK_TYPERequiredMust be set to rpc for SEP-45. This enables RPC mode for the Anchor Platform.
STELLAR_NETWORK_RPC_URLRequiredThe URL of the Stellar RPC server used to simulate transactions. You can use a public provider or run your own. A list of public providers can be found here.
SEP45_ENABLEDfalseSet to true to enable SEP-45 authentication
SEP45_HOME_DOMAINSRequiredList of home domains (comma-separated). Supports wildcard patterns like *.stellar.org. The home_domain must match the host where your stellar.toml file is served.
SEP45_WEB_AUTH_CONTRACT_IDRequiredThe contract ID of the SEP-45 contract. This contract must implement the web_auth_verify function as described in the SEP-45 specification.
SECRET_SEP10_SIGNING_SEEDRequiredThe private key corresponding to the SIGNING_KEY in your stellar.toml file. SEP-45 uses the same signing key as SEP-10. Used to sign authentication challenges.
SECRET_SEP45_JWT_SECRETRequiredThe encryption key used to sign and verify JWT tokens issued to authenticated wallets.
important
  • RPC Requirement: SEP-45 requires Stellar RPC to simulate transactions. You must set STELLAR_NETWORK_TYPE=rpc and provide a valid STELLAR_NETWORK_RPC_URL.
  • Contract ID: The SEP45_WEB_AUTH_CONTRACT_ID must match the contract deployed at the address specified in your stellar.toml file's WEB_AUTH_CONTRACT_ID field.
  • Signing Key: The SIGNING_KEY in your stellar.toml file must be the public key derived from SECRET_SEP10_SIGNING_SEED.

Optional Configuration​

# dev.env
# Optional: Specify web_auth_domain (default: first home_domain if only one is specified)
SEP45_WEB_AUTH_DOMAIN=localhost:8080

# Optional: Challenge timeout in seconds (default: 900)
SEP45_AUTH_TIMEOUT=900

# Optional: JWT token timeout in seconds (default: 86400 = 24 hours)
SEP45_JWT_TIMEOUT=86400
VariableDefaultDescription
SEP45_WEB_AUTH_DOMAINFirst home_domain if only one is specified, otherwise emptyThe web_auth_domain property used in SEP-45 responses. Required if you have multiple home_domains or use wildcard patterns. Must match the host of the SEP server.
SEP45_AUTH_TIMEOUT900Time in seconds that a challenge remains valid. Clients must sign and submit the authorization entries within this window.
SEP45_JWT_TIMEOUT86400Time in seconds that an issued JWT token remains valid. After expiration, clients must re-authenticate.
tip

Multiple Home Domains: If you specify multiple home_domains (e.g., ap.stellar.org,*.sdp.stellar.org), you must also set SEP45_WEB_AUTH_DOMAIN to specify which domain hosts the authentication endpoint.

Configure stellar.toml​

Update your stellar.toml file to advertise SEP-45 support. Wallets discover your authentication endpoint through this file.

# dev.stellar.toml

ACCOUNTS = ["add your public keys for your distribution accounts here"]
SIGNING_KEY = "add your signing key here (public key from SECRET_SEP10_SIGNING_SEED)"
WEB_AUTH_FOR_CONTRACTS_ENDPOINT = "http://localhost:8080/sep45/auth"
WEB_AUTH_CONTRACT_ID = "CD3LA6RKF5D2FN2R2L57MWXLBRSEWWENE74YBEFZSSGNJRJGICFGQXMX"

These fields should match the configuration options set in the Enable SEP-45 section above.

WEB_AUTH_FOR_CONTRACTS_ENDPOINT - The URL where the authentication service is running. This is the URL that clients will use to authenticate with the anchor. The endpoint must support:

  • GET <WEB_AUTH_FOR_CONTRACTS_ENDPOINT> - Request authorization entries
  • POST <WEB_AUTH_FOR_CONTRACTS_ENDPOINT> - Exchange signed authorization entries for session JWT

WEB_AUTH_CONTRACT_ID - The contract ID of the SEP-45 contract. This is the contract that will be used to construct the challenge. The contract must implement the web_auth_verify function as described in the SEP-45 specification. This should match SEP45_WEB_AUTH_CONTRACT_ID.

important
  • SIGNING_KEY: Must be the public key derived from SECRET_SEP10_SIGNING_SEED
  • WEB_AUTH_FOR_CONTRACTS_ENDPOINT: Use https:// in production. The path /sep45/auth is the standard SEP-45 endpoint.
  • Host Matching: The host in WEB_AUTH_FOR_CONTRACTS_ENDPOINT should match one of your SEP45_HOME_DOMAINS (or the SEP45_WEB_AUTH_DOMAIN if specified).