> ## Documentation Index
> Fetch the complete documentation index at: https://developers.stellar.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Stellar Authentication for Contract Accounts (SEP-45)

> SEP-45 (Stellar Web Authentication for Contract Accounts) enables smart wallet applications to create authenticated sessions with Stellar anchors by proving...

## 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][sep-45].

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

> [!NOTE]
>
> **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][sep-45-contract]. 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][rpc-providers].

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

```bash bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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][rpc-providers]. |
| `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][sep-45]. |
| `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. |

> [!WARNING]
>
> * **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

```bash bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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. |

> [!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.

```toml TOML theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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](#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][sep-45]. This should match `SEP45_WEB_AUTH_CONTRACT_ID`.

> [!WARNING]
>
> * **`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).

[sep1-ap]: https://developers.stellar.org/docs/platforms/anchor-platform/sep-guide/sep1.md

[sep-45]: https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0045.md

[sep-45-contract]: https://github.com/stellar/anchor-platform/tree/main/soroban/contracts/web-auth

[rpc-providers]: https://developers.stellar.org/docs/data/apis/rpc/providers.md