Skip to main content
Registration follows a three-step flow: initialize a signup session, submit account details, then verify the email address. A verified email is required before the account can be used.

​
Request

​
Step 1 — Initialize signup

POST /api/v1/auth/signup/init
No request body or authentication required. Returns a short-lived signup_token (valid for 3 minutes) that must be included in Step 2. Response
​
token
string
required
Short-lived signup token to include in the registration request.
​
expires_at
string
required
ISO 8601 expiration timestamp for the signup token.
{
  "token": "su_a1b2c3d4e5f6",
  "expires_at": "2024-01-15T10:03:00Z"
}

​
Step 2 — Create account

POST /api/v1/auth/register
No authentication required.
​
email
string
required
The new user’s email address. Must be a valid email format; used as the organization’s contact email.
​
password
string
required
Account password. Must be at least 8 characters.
​
full_name
string
required
The user’s full name. Also used as the initial organization name.
​
signup_token
string
required
The one-time token obtained from POST /api/v1/auth/signup/init.
​
country
string
ISO 3166-1 alpha-2 country code (e.g., NG, GH, KE). Used to create a local-currency balance account for your organization.
Response
​
message
string
required
Confirmation message. Indicates whether a verification email was sent.
​
user
object
required
{
  "message": "Verification code sent to your email. Please verify to activate your account.",
  "user": {
    "id": "usr_xyz789",
    "email": "jane@example.com",
    "full_name": "Jane Doe",
    "hasOnboarded": false
  }
}

​
Step 3 — Verify email

POST /api/v1/auth/verify-email
No authentication required.
​
email
string
required
The email address to verify.
​
otp
string
required
The verification code sent to the email address (4–8 characters).
Response
​
access_token
string
required
Short-lived JWT access token (valid for 15 minutes).
​
refresh_token
string
required
Long-lived refresh token (valid for 30 days).
​
user
object
required
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "rt_a1b2c3d4e5f6g7h8i9j0",
  "user": {
    "id": "usr_xyz789",
    "email": "jane@example.com",
    "full_name": "Jane Doe",
    "hasOnboarded": false
  }
}

​
Resend verification code

POST /api/v1/auth/verify-email/resend
​
email
string
required
The email address to send a new verification code to.
Response
​
message
string
required
Confirmation message.
{
  "message": "Verification code sent to your email."
}

​
Password reset

POST /api/v1/auth/forgot-password
Always returns a success response to prevent email enumeration.
​
email
string
required
The email address associated with the account.
Response 
{
  "message": "If an account exists with this email, a password reset link has been sent.",
  "isFirstTime": false
}

​
Set a new password

POST /api/v1/auth/reset-password
​
token
string
required
The reset token from the password reset email.
​
password
string
required
The new password. Must be at least 8 characters.
Response 
{
  "message": "Password has been reset successfully. You can now login with your new password."
}

​
Error codes

StatusDescription
400Missing or invalid fields, weak password, or invalid/expired signup_token.
409An account with this email already exists.

​
Example

1

Initialize a signup session

curl --request POST \
  --url https://api.syncgrampay.com/api/v1/auth/signup/init
2

Create account

curl --request POST \
  --url https://api.syncgrampay.com/api/v1/auth/register \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "jane@example.com",
    "password": "supersecret",
    "full_name": "Jane Doe",
    "signup_token": "su_a1b2c3d4e5f6",
    "country": "NG"
  }'
3

Verify email address

curl --request POST \
  --url https://api.syncgrampay.com/api/v1/auth/verify-email \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "jane@example.com",
    "otp": "482910"
  }'