Skip to main content

Developer Portal Service — API Contracts

Version: 1.0 Status: Draft Owner: Product + Developer Relations (DevRel) Last Updated: 2026-04-20

1. Intent​

Define every REST endpoint exposed by the Developer Portal Service: path, method, auth, headers, request and response schemas, error codes, and pagination. Includes the Verify API contract — the most heavily-used endpoints in this service.

2. Conventions​

  • Base URL (production): https://api.ghasi.af
  • Base URL (sandbox): https://api-sandbox.ghasi.af
  • Auth: Authorization: Bearer <apiKey> (validated by api-gateway via auth-service)
  • Versioning: URL-path (/v1)
  • Errors: { code, message, requestId }

3. Key Management Endpoints​

  • POST /devportal/v1/keys — TBD
  • GET /devportal/v1/keys — TBD
  • DELETE /devportal/v1/keys/{keyId} — TBD
  • POST /devportal/v1/keys/{keyId}/rotate — TBD

4. Verify API Endpoints​

  • POST /v1/verify/sms — TBD
  • POST /v1/verify/voice — TBD
  • POST /v1/verify/whatsapp — TBD
  • POST /v1/verify (multi-channel cascade) — TBD
  • POST /v1/verify/check — TBD
  • GET /v1/verify/{verificationId} — TBD

5. Snippet Generator​

  • GET /devportal/v1/snippets/{operationId}?lang={lang} — TBD

6. Consumption Analytics​

  • GET /devportal/v1/keys/{keyId}/consumption?range=...&granularity=... — TBD
  • GET /devportal/v1/keys/{keyId}/consumption.csv — TBD

7. SDK Release Surface​

  • GET /openapi/v1.json / /openapi/v1.yaml — TBD
  • GET /postman/v1.M.P/collection.json — TBD
  • GET /sdk/{lang}/latest — TBD

8. Error Codes​

  • TBD