API Scopes Reference

Complete reference for all 17 API scopes available in Salami Gateway. Scopes control what each API token can access, following the principle of least privilege.

Table of Contents

1. Overview
2. How Scope Enforcement Works
3. Full Access Scope
4. Payments Scopes
5. SMS Scopes
6. eTIMS Scopes
7. KRA Portal Scopes
8. Scope Groups
9. Route-to-Scope Mapping

Overview

Each API token is assigned one or more scopes (also called abilities). Scopes determine which API endpoints the token can access.

Scope Count by Module

How Scope Enforcement Works

Scope enforcement is handled by the CheckTokenScopes middleware on every API request:

1. Extract abilities -- The middleware reads the token's assigned scopes
2. Check for wildcard -- If the token has * (full access), the request is allowed
3. Match route to scope -- The current route name is checked against each scope's allowed routes
4. Grant or deny -- If a matching scope is found, access is granted; otherwise, a 403 is returned

Enforcement Flow

Request arrives with Bearer token
    |
    v
Is token valid? --[No]--> 401 Unauthorized
    |
    [Yes]
    v
Token has "*" ability? --[Yes]--> ALLOW
    |
    [No]
    v
Does any token ability include
this route? --[Yes]--> ALLOW
    |
    [No]
    v
403 Forbidden
{
  "error": "insufficient_scope",
  "required_route": "api.kra.checkers.pin",
  "your_scopes": ["payments:read"]
}

Error Response Format

{
  "success": false,
  "message": "Your API token does not have the required permissions to access this endpoint.",
  "error": "insufficient_scope",
  "required_route": "api.kra.checkers.pin",
  "your_scopes": ["payments:read", "payments:write"]
}

The error response includes required_route and your_scopes to help diagnose which scope is needed.

Full Access Scope

Grants unrestricted access to all API endpoints. Equivalent to having all 17 scopes assigned.

When to use: Administrator accounts, development/testing.

When not to use: Production integrations, third-party access, limited-purpose tokens.

Payments Scopes

payments:read

Name: Payments - Read

Description: View payment apps, transactions, balances, and statuses.

Allowed Routes:

payments:write

Name: Payments - Write

Description: Create and modify payment transactions.

Allowed Routes:

payments:callback

Name: Payments - Callbacks

Description: Handle payment provider callbacks.

Allowed Routes:

SMS Scopes

sms:read

Name: SMS - Read

Description: View SMS apps, messages, inbox, outbox, and calls.

Allowed Routes:

sms:write

Name: SMS - Send

Description: Send SMS messages to individuals and groups.

Allowed Routes:

sms:sync

Name: SMS - Sync

Description: Synchronize SMS data from mobile apps.

Allowed Routes:

sms:receive

Name: SMS - Receive

Description: Receive incoming SMS messages and callbacks.

Allowed Routes:

eTIMS Scopes

etims:read

Name: eTims - Read

Description: View eTims device info, sales, purchases, stock, items, reports, and verifications.

Allowed Routes:

etims:write

Name: eTims - Write

Description: Submit sales, credit notes, reverse invoices, purchases, stock, items, customers, and suppliers.

Allowed Routes:

etims:callback

Name: eTims - Callbacks

Description: Handle eTims/KRA callbacks and webhooks.

Allowed Routes:

KRA Portal Scopes

kra:apps

Name: KRA - App Management

Allowed Routes:

kra:checkers

Name: KRA - Checkers

Allowed Routes (13 endpoints):

kra:payments

Name: KRA - PRN Generation

Allowed Routes:

kra:compliance

Name: KRA - Tax Compliance

Allowed Routes:

kra:registration

Name: KRA - PIN Registration

Allowed Routes:

kra:returns

Name: KRA - Tax Returns

Allowed Routes:

Scope Groups

Pre-configured scope combinations for common use cases. Use these as templates when creating tokens.

Choosing Scopes

Route-to-Scope Mapping

Quick lookup -- given a 403 error with required_route, find the needed scope:

Related Documentation

• Account Tokens -- Create and manage tokens
• Webhooks -- Configure webhook notifications
• Getting Started -- Initial setup

Back to: Account Tokens | Getting Started