Skip to main content

Authentication

The Landed API supports three authentication methods, checked in this order: session cookies, API keys, and JWTs.

API keys are the recommended method for server-to-server integrations. They use the lnd_ prefix and do not expire.

Create an API Key​

curl -X POST https://api.landed.dev/auth/api-keys \
  -H "Authorization: Bearer <your-jwt>" \
  -H "Content-Type: application/json"

The response includes the raw API key. Save it immediately -- it is only returned once. Landed stores a SHA-256 hash, so the original key cannot be retrieved.

Use an API Key​

Pass the key as a Bearer token in the Authorization header:

curl https://api.landed.dev/connectors \
  -H "Authorization: Bearer lnd_abc123..."

Revoke API Keys​

Revoke all API keys for your account:

curl -X DELETE https://api.landed.dev/auth/api-keys \
  -H "Authorization: Bearer lnd_abc123..."

Session Cookies (Browser)​

The web dashboard uses httpOnly session cookies (landed_session). Sessions are set automatically after login or OAuth and expire after 30 days.

This method is used by the frontend and is not intended for programmatic access.

JWT (Short-Lived Tokens)​

JWTs are issued on login and expire after 1 hour. They are useful for short-lived operations or when bootstrapping a session.

Get a JWT​

JWTs are returned by the login and signup endpoints:

curl -X POST https://api.landed.dev/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "..."}'

Refresh a JWT​

Refresh an expired JWT (must have a valid session cookie, and the JWT must be less than 7 days old):

curl -X POST https://api.landed.dev/auth/refresh \
  -H "Authorization: Bearer <expired-jwt>" \
  -H "Cookie: landed_session=..."

Bootstrap​

The /auth/me endpoint returns customer info and a fresh JWT. It accepts any authentication method:

curl https://api.landed.dev/auth/me \
  -H "Authorization: Bearer lnd_abc123..."

Security Notes​

  • All API requests must use HTTPS
  • API keys should be stored securely and never committed to version control
  • Use environment variables or a secrets manager for API keys
  • Rotate API keys periodically by creating a new key and revoking the old ones
  • Account lockout: 5 failed login attempts trigger a 15-minute lockout