- Getting Started
- Security
Getting Started
Security
Supported protocols, rate limiting, IP allowlisting, and security best practices.
Remitian Public API is built with security and performance in mind. This guide covers rate limiting, security protocols, IP allowlisting, and best practices for integrating safely.
Supported Protocols
TLS/SSL
The Remitian Public API supports secure communications using:
- TLS 1.2 ✓
- TLS 1.3 ✓ (Recommended)
Note: Older protocols (TLS 1.0, TLS 1.1, SSL 2.0, SSL 3.0) are not supported for security reasons.
HTTP Protocols
- HTTP/1.1 ✓
- HTTP/2 ✓
All API endpoints use HTTPS to ensure encrypted communication.
Rate Limiting
Remitian Public API enforces rate limiting to ensure fair usage and maintain optimal performance for all users. The default rate limit is set to 1,000 requests per minute per Client Application. If you exceed this limit, you will receive a 429 Too Many Requests response.
Handling Rate Limits
If you receive a 429 response, it is recommended to implement an exponential backoff strategy in your application. This involves waiting for a short period before retrying the request, gradually increasing the wait time with each subsequent retry.
Example backoff strategy:
- First retry: Wait 1 second
- Second retry: Wait 2 seconds
- Third retry: Wait 4 seconds
- Continue doubling until successful or maximum attempts reached
Custom Rate Limits
For enterprise customers or specific use cases requiring higher rate limits, please contact our support team to discuss your requirements.
IP Allowlisting
Integrators can restrict Public API access to a set of known origin IPs. The allowlist is optional: without one, requests are accepted from any origin IP. With one, the token endpoint only issues access tokens to requests from a listed IP, and every authenticated request is checked against the same list before it reaches the API.
Managing the Allowlist
Members with the Editor role manage the allowlist in the Security section of the Developer Portal; Read-Only members can view it. The list applies to all Client Applications of your integrator.
| Rule | Detail |
|---|---|
| Entries | Up to 5 |
| Format | A single IPv4 address (203.0.113.10, stored as 203.0.113.10/32) or an IPv4 CIDR range (203.0.113.0/24) |
| Range size | No broader than /16; 0.0.0.0/0 is rejected |
| Canonical ranges | The address must be the network base: 203.0.113.5/24 is rejected, write 203.0.113.0/24 |
| Not accepted | IPv6 addresses, wildcards (203.0.113.*), dash ranges (203.0.113.1-50), duplicate entries, and private or non-routable space (RFC 1918, loopback, link-local, carrier-grade NAT, multicast, reserved) |
Clearing the list turns enforcement off; there is no separate enable or disable switch.
Propagation
- Enabling an allowlist applies to access tokens issued afterwards. Tokens issued before it keep working until they expire (10 minutes by default).
- Edits to an existing list take effect within one minute.
- Requests from IPv6 origins never match an entry, so with an allowlist configured they are refused. Make sure your systems reach the API over IPv4 from a listed address.
Responses When Blocked
| Request | Response |
|---|---|
POST /v1/auth/token from an origin not on the list | 401 Unauthorized, the same response as invalid credentials |
| Any authenticated request from an origin not on the list | 403 Forbidden |
Neither response reveals the configured entries. The Developer Portal itself is not subject to the allowlist, so an Editor can always correct the list after a lockout.
Security Best Practices
Credential Management
- Never expose your Client Secret in client-side code or public repositories
- Store credentials securely using environment variables or secure credential management systems
- Rotate your credentials periodically
- Use the most restrictive scope necessary for your integration
Self-Service Credentials: Credentials are generated, copied, and regenerated directly in the Developer Portal — they are never sent by email. Members with the Editor role can rotate the API Key and API Secret at any time.
Credential Compromise Response: If your Client Secret is inadvertently shared, compromised, or exposed (e.g., committed to a public repository, sent via email, or shared in insecure channels), immediately regenerate it in the Developer Portal (Client Applications → Regenerate) to invalidate the exposed credential. If you need assistance, contact support@remitian.com. Do not delay—compromised credentials pose a serious security risk to your integration and data.
Request Security
- Always use HTTPS for all API requests
- Restrict API access to your servers’ egress IPs with an IP allowlist (see IP Allowlisting above)
- Validate SSL/TLS certificates in your client applications
- Implement proper error handling for authentication failures
- Log security events for monitoring and audit purposes
Webhook Security
- Verify the
payload-signatureheader (HMAC-SHA256) on every webhook delivery — see the Webhooks guide - Keep your webhook signature token secret and rotate it periodically from the Developer Portal
- If your firewall restricts inbound traffic, allow only the Remitian webhook source IP addresses listed in the Webhooks guide
TIN Security
TIN encryption applies only when you filter tax entities or taxpayers by TIN (GET /v1/taxpayers/{taxpayerId}/tax-entities?encryptedTin={encryptedTin} or GET /v1/firms/{firmId}/taxpayers?encryptedTin={encryptedTin}). Every other request, including creating a tax entity, sends the TIN as documented and needs no encryption key or setup.
- Never send a TIN in plaintext in a URL; to find a tax entity or a taxpayer by TIN, encrypt it and send it in
encryptedTin. See the Filter Tax Entities by TIN and Use Case 3: Manage Taxpayers guides - Download the TIN encryption public key only from the Developer Portal of the environment you call
- Encrypt the TIN right before each filter request, and never log or store the TIN in plaintext
SFTP File Delivery Security
- Keep your SSH and PGP private keys on your systems only; share only the public keys
- Verify the server host key fingerprint before your first connection, and do not connect if your client reports a changed host key
- Verify the Remitian signature on every file before you use it
- Rotate your SSH keys periodically from the Developer Portal; see the SFTP File Delivery guide
Need Help?
Our support team is here to assist you:
- Email: support@remitian.com
- Response Time: Within 1-2 business days