01 - Authentication & Team

1. Authentication flow at a glance

sequenceDiagram
    autonumber
    participant Dev as Developer App
    participant API as DigetPay API v1
    participant Notify as SMS / Email OTP

    Dev->>API: POST /developer-portal/register
    API-->>Notify: Send OTP
    API-->>Dev: 201 - {challengeId, expiresIn, email}

    Dev->>API: POST /developer-portal/register/verify-otp
    API-->>Dev: 200 - {ok: true, verified: true}

    Dev->>API: POST /developer-portal/auth/login
    API-->>Notify: Send OTP
    API-->>Dev: 200 - {challengeId, expiresIn, email}

    Dev->>API: POST /developer-portal/auth/login/verify-otp
    API-->>Dev: 201 - {accessToken, refreshToken, tokenType, expiresIn, user, organization}

    Note over Dev,API: Access token valid for 12 hours

    Dev->>API: GET /developer-portal/auth/me - Bearer token
    API-->>Dev: 200 - {user, organization, applicationCount}

    Dev->>API: POST /developer-portal/auth/refresh
    API-->>Dev: 200 - pair rotated

    Dev->>API: POST /developer-portal/auth/logout
    API-->>Dev: 200 - {ok: true}

2. Token contract

3. Registration

POST /developer-portal/register — public

Creates the organization (ONBOARDING) + owner + verification (DRAFT)
atomically.

{
  "companyName": "Acme Payment Solutions",
  "legalName": "Acme Payment Solutions LLC",
  "email": "[email protected]",
  "phone": "+966501234567",
  "fullName": "Sarah Developer",
  "password": "SecurePass123"
}

Response 201

{
  "challengeId": "a1b2c3d4e5f60718293a4b5c",
  "expiresIn": 600,
  "email": "[email protected]"
}

POST /developer-portal/register/verify-otp — public

{ "challengeId": "a1b2c3d4e5f60718293a4b5c", "otp": "123456" }

Response 200

{ "ok": true, "verified": true }

POST /developer-portal/register/resend-otp — public

{ "challengeId": "a1b2c3d4e5f60718293a4b5c" }

Response 200

{ "expiresIn": 600 }

4. Login

POST /developer-portal/auth/login — public

{ "email": "[email protected]", "password": "SecurePass123" }

Response 201 — same challenge shape as registration:

{ "challengeId": "a1b2c3d4e5f60718293a4b5c", "expiresIn": 600, "email": "[email protected]" }

POST /developer-portal/auth/login/verify-otp — public

{ "challengeId": "a1b2c3d4e5f60718293a4b5c", "otp": "123456" }

Response 201 — save the tokens:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
  "refreshToken": "4f6b2a1c8e9d0f1a2b3c4d5e6f708192",
  "tokenType": "Bearer",
  "expiresIn": 43200,
  "user": { "id": "10", "email": "[email protected]", "name": "Sarah Developer" },
  "organization": {
    "id": "42",
    "name": "Acme Payment Solutions",
    "legalName": "Acme Payment Solutions LLC",
    "status": "ONBOARDING"
  }
}

5. Session endpoint — GET /developer-portal/auth/me

Returns profile + organization + application count. Used to confirm a live
session.

{
  "user": { "id": "10", "email": "[email protected]", "name": "Sarah Developer", "role": "OWNER" },
  "organization": { "id": "42", "name": "Acme Payment Solutions", "status": "APPROVED" },
  "applicationCount": 3
}

The role tells you what the account can do: an OWNER is a company admin with
full control; a DEVELOPER can build and maintain the integration but cannot
edit company data, manage the marketplace listing, view refunds, open tickets, or
manage team members.

6. Refresh & logout

POST /developer-portal/auth/refresh

{ "refreshToken": "4f6b2a1c8e9d0f1a2b3c4d5e6f708192" }

Response 200 — pair rotated, previous refresh token revoked:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
  "refreshToken": "0a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "tokenType": "Bearer",
  "expiresIn": 43200
}

POST /developer-portal/auth/logout

{ "refreshToken": "0a1b2c3d4e5f60718293a4b5c6d7e8f90" }

Response 200 — { "ok": true }

7. Password recovery

8. Authentication error reference

9. Team management & roles

Every developer organization starts as a single OWNER account created by
self-registration. The OWNER can invite colleagues as DEVELOPER members who
help with the integration work.

9.1 Roles

Only an OWNER can manage team members; invites always create a DEVELOPER
account — the team API can never create or reassign an OWNER.

GET /auth/me returns the member's role, so your app can tailor its UI.

9.2 Team lifecycle

stateDiagram-v2
    [*] --> PENDING : owner invites
    PENDING --> ACTIVE : activation link + password
    PENDING --> [*] : invite expires / removed
    ACTIVE --> INACTIVE : owner removes

The OWNER is ACTIVE from self-registration — it never passes through PENDING.

9.3 Invite → activate → login

1. Owner sends POST /developer-portal/team/invite with email and fullName;
   the server creates a PENDING member and emails an activation link.
2. The invitee clicks the link and sets their password via
   POST /developer-portal/auth/activate with the token and newPassword;
   the account becomes ACTIVE.
3. The invitee signs in through the normal login flow and receives a JWT with
   the DEVELOPER role.

9.4 API reference

List members — GET /developer-portal/team — Bearer, owner-only

Returns every member: the OWNER plus all invited DEVELOPER accounts.

curl -X GET \
  "https://fin-api.digetpay.com/v1/developer-portal/team" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response 200 — TeamMember[]

[
  {
    "id": "10",
    "email": "[email protected]",
    "name": "Sarah Developer",
    "role": "OWNER",
    "status": "ACTIVE",
    "invitedByUserId": null,
    "inviteExpiresAt": null,
    "lastLoginAt": "2026-08-20T09:00:00.000Z",
    "createdAt": "2026-07-01T08:00:00.000Z"
  },
  {
    "id": "11",
    "email": "[email protected]",
    "name": "Ali Mohammed",
    "role": "DEVELOPER",
    "status": "PENDING",
    "invitedByUserId": "10",
    "inviteExpiresAt": "2026-08-29T10:00:00.000Z",
    "lastLoginAt": null,
    "createdAt": "2026-08-26T10:00:00.000Z"
  }
]

Invite a DEVELOPER — POST /developer-portal/team/invite — Bearer, owner-only

Creates a PENDING DEVELOPER member and emails the activation link.

curl -X POST \
  "https://fin-api.digetpay.com/v1/developer-portal/team/invite" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "email": "[email protected]",
    "fullName": "Ali Mohammed"
  }'

Response 200

{
  "ok": true,
  "developerUserId": "11",
  "role": "DEVELOPER",
  "status": "PENDING",
  "inviteExpiresAt": "2026-08-29T10:00:00.000Z",
  "emailSent": true
}

• Re-inviting an existing PENDING member refreshes the invitation (same
  response) instead of creating a duplicate.
• If email delivery fails, the created member is rolled back and the request
  fails.

Resend an invitation — POST /developer-portal/team/:userId/resend-invite — Bearer, owner-only

Refreshes the invitation expiry and sends a new activation link.

curl -X POST \
  "https://fin-api.digetpay.com/v1/developer-portal/team/11/resend-invite" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response 200

{ "ok": true, "inviteExpiresAt": "2026-08-29T11:00:00.000Z", "emailSent": true }

Remove a member — DELETE /developer-portal/team/:userId — Bearer, owner-only

PENDING accounts are deleted outright; ACTIVE/INACTIVE accounts are
deactivated and their sessions revoked. The OWNER can never be removed.

curl -X DELETE \
  "https://fin-api.digetpay.com/v1/developer-portal/team/11" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response 200 — { "ok": true }

Activate an invited account — POST /developer-portal/auth/activate — public

Completes the invite: the invitee clicks the activation link, which opens the
activate page; the page reads the token from the URL and calls this endpoint to
set the password and activate the account.

curl -X POST \
  "https://fin-api.digetpay.com/v1/developer-portal/auth/activate" \
  -H "Content-Type: application/json" \
  --data '{
    "token": "a1b2c3d4e5f6a7b8",
    "newPassword": "secure-pass-2026"
  }'

Response 200 — { "ok": true }

• The activation link expires after 72 hours; the OWNER must resend after
  that.
• After activation, future password resets go through forgot-password — the
  activation token works only once.

9.5 Team business rules

9.6 Team errors

9.7 Security considerations

• Removing a member revokes their access immediately.
• The activation token is an opaque random string (not a JWT), exposed only
  through the invite email link and never returned in an API response.
• Team email addresses are company-confidential; treat the GET /team response
  accordingly.

10. Summary

• Public endpoints cover register → OTP → login → OTP → tokens, plus
  activate for invited DEVELOPER members.

  Authenticated calls use Authorization: Bearer with a
  developer-portal-access JWT.

• Refresh tokens rotate; logout revokes.

• Team management and role capabilities live in §9.