Storefront Auth
Raw customer OTP endpoints on the storefront API. New storefronts should prefer SDK OAuth sign-in; these endpoints remain available for direct API integrations.
Use the SDK flow in Sign in with Cimplify for normal
storefront sign-in and embedded checkout. This page documents the raw
/api/v1/auth/* endpoints exposed by the storefront API.
All endpoints use the storefront response envelope:
{ "data": { "...": "..." } }GET /api/v1/auth/status
Returns the authenticated customer for the active bearer session.
curl https://storefronts.cimplify.io/api/v1/auth/status \
-H "X-API-Key: cpk_test_your_publishable_key" \
-H "Authorization: Bearer <session_token>"{
"data": {
"is_authenticated": true,
"customer": {
"id": "cus_01H...",
"name": "Ama Mensah",
"email": "ama@example.com",
"phone": "+233241234567"
},
"session_expires_at": "2026-05-31T12:00:00Z"
}
}Guest sessions return is_authenticated: false and omit customer.
POST /api/v1/auth/request-otp
Send a one-time code to a phone number or email.
| Field | Type | Description |
|---|---|---|
contact | string | E.164 phone number or email. |
contact_type | "phone" or "email" | Optional. Defaults to phone when omitted. |
curl -X POST https://storefronts.cimplify.io/api/v1/auth/request-otp \
-H "X-API-Key: cpk_test_your_publishable_key" \
-H "Content-Type: application/json" \
-d '{"contact": "+233241234567", "contact_type": "phone"}'{
"data": {
"message": "OTP sent to +233****4567",
"expires_in": 300,
"is_new_account": false
}
}POST /api/v1/auth/verify-otp
Exchange the code for a customer session token. The SDK stores
session_token with client.setAccessToken(...) and sends it as
Authorization: Bearer ... on later customer-scoped calls.
| Field | Type | Description |
|---|---|---|
contact | string | Same contact used for request-otp. |
otp_code | string | 4-6 character one-time code. |
contact_type | "phone" or "email" | Optional. Defaults to phone when omitted. |
curl -X POST https://storefronts.cimplify.io/api/v1/auth/verify-otp \
-H "X-API-Key: cpk_test_your_publishable_key" \
-H "Content-Type: application/json" \
-d '{
"contact": "+233241234567",
"contact_type": "phone",
"otp_code": "847362"
}'{
"data": {
"message": "Successfully authenticated",
"account_id": "acc_01H...",
"session_token": "eyJ...",
"refresh_token": "eyJ...",
"customer": {
"id": "cus_01H...",
"name": "Ama Mensah",
"email": "ama@example.com",
"phone": "+233241234567"
}
}
}Errors
| HTTP | Code | Meaning |
|---|---|---|
400 | VALIDATION_ERROR | Contact or otp_code failed validation. |
401 | INVALID_OTP | Code expired, mismatched, or already redeemed. |
429 | RATE_LIMITED | Too many attempts. |
POST /api/v1/auth/logout
Clear the local session in the caller. Direct API clients should discard the
current bearer token when they receive action: "discard_token".
curl -X POST https://storefronts.cimplify.io/api/v1/auth/logout \
-H "X-API-Key: cpk_test_your_publishable_key" \
-H "Authorization: Bearer <session_token>"{
"data": {
"message": "Successfully logged out",
"action": "discard_token"
}
}POST /api/v1/auth/profile
Update one or more fields on the authenticated customer profile.
| Field | Type | Description |
|---|---|---|
name | string | Optional display name. |
email | string | Optional email. |
phone | string | Optional phone. |
curl -X POST https://storefronts.cimplify.io/api/v1/auth/profile \
-H "X-API-Key: cpk_test_your_publishable_key" \
-H "Authorization: Bearer <session_token>" \
-H "Content-Type: application/json" \
-d '{"name": "Ama N. Mensah"}'{
"data": {
"success": true,
"message": "Profile updated successfully"
}
}Related
Checkout
Create a durable purchase intent, review immutable terms and an exact payment option, then confirm it idempotently. An Order does not exist until confirmation commits.
Orders
Read and manage Orders created only after purchase-intent confirmation. Historical Order-token reads remain supported for pre-convergence records.