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
Convert the active cart into an order, run payment, and return everything the caller needs to confirm or redirect. The body is **flat**: fields like `cart_id`, `customer`, and `payment_method` sit at the top level. There is no `checkout_data` wrapper.
Orders
Read and manage orders created by checkout. Authenticated customers get their own orders; guests can access individual orders by passing the order’s `bill_token` as a query parameter.