Authentication & Scopes
Use OAuth and personal access tokens securely with least-privilege scopes.
Authentication & Scopes
Access to the NidFul API requires strong authentication aligned with our enterprise security controls. This guide walks you through OAuth, personal access tokens, and how to scope them correctly for least privilege.
OAuth 2.0 Applications
Use OAuth when integrating NidFul with internal systems or third-party platforms.
- Navigate to Admin → Integrations → OAuth Apps.
- Register a new application with redirect URIs (HTTPS only).
- Capture the Client ID and Client Secret.
- Use the authorization code flow to exchange a code for an access token.
Authorization URL
https://api.nidful.com/oauth/authorize?client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}&response_type=code&scope=submissions:read
Token URL
POST https://api.nidful.com/oauth/token
grant_type=authorization_code
code={AUTH_CODE}
redirect_uri={REDIRECT_URI}
Tokens expire after 2 hours. Use refresh tokens to obtain new access tokens without requiring user interaction.
Personal Access Tokens (PATs)
- Ideal for automation scripts or CI pipelines.
- Scoped to a single user; revocation immediately invalidates the token.
- Rotate PATs every 90 days to align with compliance best practices.
Available Scopes
| Scope | Description |
| --- | --- |
| submissions:read | View reports, comments, attachments |
| submissions:write | Create comments, update statuses |
| programs:read | Read program metadata and policies |
| payouts:write | Trigger bounty payments (requires finance role) |
| analytics:read | Access reporting endpoints |
Use least privilege
Assign only the scopes required for each automation. Excessive permissions are the leading cause of API misuse incidents.
Web Application Firewall (WAF)
- All API traffic passes through a WAF tuned for abuse signatures common in Africa (SIM swap tooling, botnets).
- Rate limits apply per token and per IP; see Rate Limits & Error Handling.
Testing & Sandbox
- Use the sandbox environment
https://sandbox.api.nidful.comfor integration testing. - Sandbox tokens are isolated and cannot impact production data.
Revocation & Audit
- Revoke tokens in the dashboard or via
DELETE /v1/auth/tokens/{tokenId}. - Audit logs include token creation, last use, and originating IP ranges.
Next, explore Core REST Endpoints to see how authentication plugs into data workflows.