- Getting Started
- Authentication
Getting Started
Authentication
Obtain credentials, request access tokens, choose scopes, and make authenticated requests.
Before you can start making requests to the Remitian Public API, you’ll need to obtain your API credentials. Follow the steps below to get started:
1. Contact Support
Currently, account creation is managed through our support team. Please contact us at support@remitian.com to request access.
2. Get Your Credentials
Once your access is aligned with our team, you’ll receive an invitation to sign up to the Developer Portal. During onboarding you will also receive your External Integration ID — a unique identifier for your system. Within an external integrator, you can have multiple Client Applications.
Your Client Application Credentials are generated by you in the Developer Portal:
- Client ID
- Client Secret
- API Key
Self-Service Credentials: Create a Client Application in the Developer Portal to generate its credentials, then copy them directly from the portal — they are never sent by email. Members with the Editor role can regenerate the API Key or API Secret at any time.
Example of the credentials you will use:
{
"externalIntegrationId": "019bc3f4-d65e-73f7-8133-f5800e825509",
"clientApplicationId": "019b2952-c553-7a93-ba57-d3baf8e09cb0",
"apiSecret": "sec_8499e437e8908d68a6fdecb9f5544884e510994bbf6674565468e1250ab3478d",
"apiKey": "api_019bc3f4-d65f-7459-b22a-a82339248261"
}
Important: Store the Client Secret securely. Never commit it to version control or expose it in client-side code. Once the Client Secret is generated, it will not be shown again for security reasons. If you lose it, regenerate it in the Developer Portal.
Security Alert: If your Client Secret is inadvertently shared, compromised, or exposed (e.g., committed to a public repository), immediately regenerate it in the Developer Portal (Client Applications → Regenerate). The old credential is invalidated instantly. If you need assistance, contact support@remitian.com. Do not delay—compromised credentials pose a serious security risk to your integration and data.
3. Get Access Tokens
With your Client ID and Client Secret, you can now obtain access tokens to authenticate your API requests.
To authenticate and get an access token, make a POST request to the authentication endpoint:
Endpoint:
POST https://public-api.remitian.com/v1/auth/token
Content-Type: application/json
Request Body:
{
"externalIntegratorId": "{{yourExternalIntegratorId}}",
"clientApplicationId": "{{yourClientApplicationId}}",
"apiSecret": "{{yourClientSecret}}",
"scope": "{{scope}}"
}
Scope Options
Choose the appropriate scope based on your needs:
| Scope | Access Level | Use Case |
|---|---|---|
all | Full access to all firms and taxpayers | Full administrative access within the Client Application |
firm:{firmId} | Specific firm only | Access limited to a single firm and its taxpayers |
firm:{firmId}:firmUser:{firmUserId} | Specific firm user | Access limited to a specific user within a firm |
taxpayer:{taxpayerId} | Specific taxpayer | Access limited to a single taxpayer and their resources |
Choosing the Right Scope
Security Requirement: Tokens must always be generated server-side (backend) because they contain the Client Secret. Never generate tokens in client-side code or expose the Client Secret to browsers or mobile apps.
For Server-Side Only Usage:
When the token will only be used by your backend services:
- Prefer limited scope whenever possible for better security
- Use
allorfirm:{firmId}for general operations - If you only need to access a specific firm user’s resources, use
firm:{firmId}:firmUser:{firmUserId} - If you only need to access a specific taxpayer’s resources, use
taxpayer:{taxpayerId}
For Client-Side Usage:
When your backend generates a token to be used by a client (browser/mobile app), choose the scope based on what the user should access:
| User’s Access Need | Recommended Scope |
|---|---|
| Manage all firms in the Client Application | all |
| Manage resources of a specific entire firm | firm:{firmId} |
| Manage resources of a specific firm user | firm:{firmId}:firmUser:{firmUserId} |
| Manage resources of a specific taxpayer | taxpayer:{taxpayerId} |
Security Best Practice: Always use the most restrictive scope necessary for your use case. For instance, if a user is a firm accountant managing their own clients, use firm:{firmId}:firmUser:{firmUserId} rather than firm:{firmId} or all.
4. Make Authenticated API Requests
Every subsequent API request must include:
- Access Token in the
Authorizationheader - API Key in the
x-api-keyheader
Example Request:
GET https://public-api.remitian.com/v1/health
Authorization: Bearer {{yourAccessToken}}
x-api-key: {{yourApiKey}}
5. IP Allowlisting (Optional)
Your organization can restrict Public API access to known origin IPs. Members with the Editor role manage the allowlist in the Security section of the Developer Portal, and it applies to every Client Application of your integrator.
- No allowlist configured: requests are accepted from any origin IP.
- Allowlist configured: access tokens are only issued to requests coming from a listed IP, and every subsequent API request is checked against the same list before it reaches the API.
When the origin IP is not on the list, the token endpoint responds with 401 Unauthorized (the same response as invalid credentials) and authenticated requests respond with 403 Forbidden. Neither response reveals the configured entries.
See IP Allowlisting in the Security guide for entry rules, limits and propagation times.
Next Steps
You’re now ready to start building with the Remitian Public API!
- Getting Started Guide - Complete integration walkthrough
- Environments - Learn about sandbox vs production
- Security Best Practices - Keep your integration secure
- Use Cases - Real-world integration examples