Skip to main content
Ed25519 authentication is the recommended method for backend services, SDKs, and server-to-server integrations. It uses the Ed25519 signature scheme — a specific implementation of the Edwards-curve Digital Signature Algorithm (EdDSA), which belongs to the Elliptic Curve Cryptography (ECC) family. Your application proves it controls a cryptographic key pair by signing a challenge issued by the gateway.

​
When to use

Use Ed25519 authentication when your integration is a backend service that:
  • Calls the Zeam API from a server (not a browser or mobile app)
  • Has access to a private key stored in a secret manager
  • Needs access to Connect endpoints (/v1/connect-*) or application management

​
How it works

The gateway issues a cryptographic challenge bound to your application’s public key. Your server signs this challenge with the corresponding Ed25519 private key and submits the signature. The gateway verifies the signature and issues a bearer token.

​
Step by step

1

Fetch the challenge

Request a challenge for your application’s public key:
curl -s "https://api.zeam.money/gw/v1/public/auth-connect?account=$ZEAM_APP_PUBLIC_KEY" | jq
The response contains a challenge payload that must be signed with your private key.
2

Sign the challenge

Sign the challenge with your Ed25519 private key. The private key must never leave your server.
import "github.com/ZeamMoney/zeam-sdk-go/crypto"

signature, _ := crypto.SignChallenge(challenge, privateKey)
3

Submit the signed challenge

curl -s -X POST https://api.zeam.money/gw/v1/public/auth-connect \
  -H 'Content-Type: application/json' \
  -d '{"transaction": "'$SIGNED_CHALLENGE'"}' | jq
Response:
{
  "idToken": "eyJhbGciOi...",
  "refreshToken": "dGhpcyBpcyBh...",
  "expiresIn": 3600
}
4

Use the token

Include the idToken as a bearer token on every API call:
curl -s https://api.zeam.money/gw/v1/business/association/all \
  -H "Authorization: Bearer $ID_TOKEN"

​
Using the Go SDK

The SDK handles the entire flow in a single call: 
import (
    "github.com/ZeamMoney/zeam-sdk-go"
    "github.com/ZeamMoney/zeam-sdk-go/recipes"
)

client, _ := zeam.New(zeam.WithEnvironment(zeam.EnvironmentProduction))

sess, err := recipes.ConnectLogin(ctx, client, recipes.ConnectLoginInput{
    StellarSeed: seed,       // from your secret manager
    PublicKey:   publicKey,
})

​
Endpoints

MethodPathPurpose
GET/v1/public/auth-connect?account=<G...>Fetch a challenge
POST/v1/public/auth-connectSubmit the signed challenge
POST/v1/public/auth-connect/sign-inServer-side convenience (single request)
POST/v1/public/auth/refreshExchange refreshToken for a new idToken

​
Server-side sign-in

POST /v1/public/auth-connect/sign-in collapses the flow into a single request by sending both the public key and secret issued during application registration.
This is the simplest way to authenticate for Connect execution. The Go SDK wraps this call in recipes.ConnectLogin.

​
Troubleshooting

SymptomLikely cause
400 on submitChallenge was not signed, or signed with the wrong private key
401 on /v1/* callsidToken has expired — refresh via POST /v1/public/auth/refresh
Empty responseThe authentication service is unreachable — check your network and retry