QueryFind (or create) user by email address

Find (or create) user by email address

Looks up a user by email address. By default, if the user does not exist, creates them in both D1 (read model) and UserAggregate (event sourcing). This endpoint is idempotent — safe to call multiple times for the same email. Pass searchOnly=true to look up ONLY: a miss then answers 404 and nothing is created.

curl -X GET "https://api.spkey.co/users/by-email?email=user%40example.com&uuid=example_string&searchOnly=true" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN (JWT)" \
  -H "X-API-Key: YOUR_API_KEY"
{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "created_at": "2024-01-15T10:30:00.000Z"
}
GET
/users/by-email
GET
Base URLstring

Target server for requests. Edit to use your own host.

Bearer Token (JWT)
Bearer Tokenstring
Required

JWT token from SmartphoneKey authentication. Identifies the B2C user or B2B service.

JWT token from SmartphoneKey authentication. Identifies the B2C user or B2B service.
API Key (header: X-API-Key)
X-API-Keystring
Required

API key for B2B organization access. Provided during organization onboarding.

API key for B2B organization access. Provided during organization onboarding.
query
emailstring
Required

User email address

query
uuidstring

Optional UUID to assign to the new user

query
searchOnlystring

When true, only look the user up — do not create one on a miss (404 instead). Defaults to false, which keeps the existing find-or-create behaviour.

Options: true, false
Request Preview
Response

Response will appear here after sending the request

Authentication

header
Authorizationstring
Required

Bearer token (JWT). JWT token from SmartphoneKey authentication. Identifies the B2C user or B2B service.

header
X-API-Keystring
Required

API Key for authentication. API key for B2B organization access. Provided during organization onboarding.

Query Parameters

emailstring
Required

User email address

uuidstring

Optional UUID to assign to the new user

searchOnlystring

When true, only look the user up — do not create one on a miss (404 instead). Defaults to false, which keeps the existing find-or-create behaviour.

Allowed values:truefalse

Responses

uuidstring
Required
emailstring
Required
created_atstring
Required