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-45: 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

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

The Client requests a unique challenge from the Server
The Client verifies and signs the challenge
The Client submits the signed challenge to the Server
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)

Variable	Default	Description
`STELLAR_NETWORK_TYPE`	Required	Must be set to `rpc` for SEP-45. This enables RPC mode for the Anchor Platform.
`STELLAR_NETWORK_RPC_URL`	Required	The 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_ENABLED`	`false`	Set to `true` to enable SEP-45 authentication
`SEP45_HOME_DOMAINS`	Required	List 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_ID`	Required	The 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_SEED`	Required	The 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_SECRET`	Required	The encryption key used to sign and verify JWT tokens issued to authenticated wallets.

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

Variable	Default	Description
`SEP45_WEB_AUTH_DOMAIN`	First `home_domain` if only one is specified, otherwise empty	The `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_TIMEOUT`	`900`	Time in seconds that a challenge remains valid. Clients must sign and submit the authorization entries within this window.
`SEP45_JWT_TIMEOUT`	`86400`	Time in seconds that an issued JWT token remains valid. After expiration, clients must re-authenticate.

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.

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).

​Overview

​Typical Authentication Flow

​Enable SEP-45

​Required Configuration (If Enabled)

​Optional Configuration

​Configure stellar.toml

Overview

Typical Authentication Flow

Enable SEP-45

Required Configuration (If Enabled)

Optional Configuration

Configure stellar.toml