---
title: 08.03 Permissions and the API
description: API permissions are SimpleRisk user permissions. The API key inherits the user's role, direct grants, admin flag, and team membership. To restrict an…
---
[Skip to content](https://support.simplerisk.com/kb/08-03-permissions-and-the-api#main-content)
English
Show submenu for translations
[Customer portal](https://support.simplerisk.com/tickets?hsLang=en)
[](https://www.simplerisk.com/)
Open main navigation
Close main navigation
- English
Show submenu for translations
- [Customer portal](https://support.simplerisk.com/tickets)
- [Contact us](https://www.simplerisk.com/about-us/contact-us)
[Contact us](https://www.simplerisk.com/about-us/contact-us)
How can we help you?
- There are no suggestions because the search field is empty.
1. [SimpleRisk Knowledge Base](https://support.simplerisk.com/kb?hsLang=en)
2. [Administrator Guide](https://support.simplerisk.com/kb/administrator-guide?hsLang=en)
3. [08 The API](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#08-the-api)
# 08.03 Permissions and the API
## API permissions are SimpleRisk user permissions. The API key inherits the user's role, direct grants, admin flag, and team membership. To restrict an integration's capabilities, restrict the user's permissions; to broaden them, broaden the user's. There's no separate API permission model.
## Why this matters
Most production integration mistakes trace to a permission misunderstanding. The integration submits a risk and gets a 403; the developer thinks the API is broken; the actual cause is the integration user lacks `submit_risks`. The integration reads risks and gets back an empty list; the developer thinks something's wrong; the actual cause is team-membership filtering. Understanding how permissions interact with API requests prevents most of these wrong-track debugging sessions.
The model itself is simple: **API permissions are user permissions**. The key inherits everything the user has — role, direct grants, admin flag, team memberships. There's no separate "API can do X but not Y" layer. Restricting the integration means restricting the user account behind the key; broadening it means broadening the user.
This article covers how this plays out in practice. For the broader permission model, see [The Permission Model](https://support.simplerisk.com/kb/03-02-the-permission-model?hsLang=en).
## How API requests resolve permissions
When a request hits an authenticated endpoint:
1. The API key is extracted and the user identified (see [Authentication and API Keys](https://support.simplerisk.com/kb/08-02-authentication-and-api-keys?hsLang=en)).
2. The user's effective permissions are loaded — the union of role-derived permissions, direct per-user grants, and admin override.
3. The user's team memberships are loaded.
4. The endpoint handler executes the operation as that user. Permission checks and team filters apply exactly as they would in the browser.
The same code path runs whether the user came in via the web UI or the API. There's no separate "API permission" branch.
## What this means in practice
### The integration user's role is the integration's role
If you create a user `slack-bot` with the role "Risk Submitter," the API integration acting as that user can do exactly what a Risk Submitter can do — submit risks, view risks, but not modify configuration or other users. Want the integration to be able to close risks too? Either add the close-risks permission to the Risk Submitter role (affecting every Risk Submitter, not just the integration) or grant the permission directly to the `slack-bot` user.
The pattern: **create one SimpleRisk user per integration**, assign the role that matches the integration's needs, add per-user permission grants for any integration-specific capabilities the role doesn't cover.
### Team membership filters the integration's view
A user on the Engineering team only sees Engineering's records. The API enforces this — `GET /api/v2/risks` returns risks visible to the user, not all risks in the database.
If your integration needs to see risks across multiple teams (e.g., a centralized dashboard), the integration user needs team memberships covering those teams. For "see everything" integrations, either:
- Add the user to every team, OR
- Set the user's `admin` flag to `1` (which bypasses team filtering entirely, but is a much broader grant).
The admin-flag approach is convenient but dangerous — the integration can do anything in SimpleRisk, including modify other users' records and change critical configuration. Prefer adding the user to specific teams when possible.
### Permission-denied responses
When the user lacks permission for an operation:
- **403 Forbidden** — the standard response for permission denial.
- The response body includes a `status_message` indicating the denial.
The 403 isn't an authentication failure — the key is valid; the user just can't do the requested operation. Check the user's permissions in SimpleRisk's User Management UI.
A handful of older endpoints deny with **401 Unauthorized** rather than 403, carrying the `status_message` "Unauthorized Access. The authenticated user does not have proper permissions." Treat that message, not the status code, as the reliable signal: an integration that branches on the code alone will misread these denials as an expired or invalid key and may retry or re-authenticate pointlessly. Distinguish them from a genuine authentication failure, which returns "Unauthenticated Access. Please log in or provide a key to use the SimpleRisk API."
### What gets logged on a denial
Don't assume a denied API call leaves a `warning` in the log — what you get depends on which check refused the request:
- **Page-level and sink-level denials (file downloads, the compliance test-result risk closure):** `warning`
- **A named permission being refused:** `info` — "does not have the '`{permission}`' permission"
- **An admin-only endpoint refusing a non-admin:** nothing
Only the first row is a `warning`. The endpoints that answer 401 through the API's shared unauthorized-access helper write no log entry of their own, so for those the `info` line about the missing permission — or, for admin-gated endpoints, the HTTP response alone — is the only trace. If you are troubleshooting a denial you cannot find in the log, raise `logging_info` before concluding the request never arrived.
### Admin override
A user with `admin = 1` bypasses all permission checks. The API key for an admin user can do anything: submit risks, modify users, deactivate Extras, change settings, generate other users' API keys.
This is appropriate for human-operator accounts; it's almost never appropriate for integration accounts. Compromise of an admin key compromises the entire SimpleRisk install. Use admin keys exclusively for break-glass scenarios; create dedicated, least-privileged users for routine integrations.
### Per-user direct grants
The User Management UI lets you grant specific permissions to a user beyond their role's default. This is useful for integration users that need a slightly-different permission set than any defined role:
- Pick a role that's mostly right.
- Grant the additional permissions directly to the user.
- The user's effective permission set is the union.
For integrations that recur, the grant pattern often repeats — at which point it's worth defining a new role specifically for that integration pattern.
## Designing permissions for integrations
### Pattern A: Read-only reporting integration
Goal: a script that reads risk data for an external dashboard.
- **Role**: a custom "API Reader" role with view permissions for the relevant entities (`view_risks`, `view_compliance`, etc.) and no write permissions.
- **Teams**: every team the dashboard should display data for.
- **Admin flag**: `0`.
- **Verify**: the user can `GET /api/v2/risks` (returns expected data) but `POST /api/v2/risks/submit` returns 403.
### Pattern B: Risk submitter integration
Goal: a script that imports risks from an external source weekly.
- **Role**: a custom "API Submitter" role with `submit_risks` and the necessary related permissions.
- **Teams**: the team(s) the imported risks should be assigned to (so they're visible to the right users via team-segregation).
- **Admin flag**: `0`.
- **Verify**: the user can `POST /api/v2/risks/submit` (creates a risk) and the created risk appears for users on the same team(s).
### Pattern C: Risk-state-update integration
Goal: a CI pipeline that closes risks when corresponding fixes ship.
- **Role**: a custom "API CI" role with `modify_risks` and `close_risks` (and the related team-scoped equivalents).
- **Teams**: the team the risks the CI manages belong to.
- **Admin flag**: `0`.
- **Verify**: the user can `PATCH /api/v2/risks/{id}` to update the relevant risks but can't modify other team's risks (403).
### Pattern D: Admin operations integration
Goal: a script that bulk-creates users from an HR feed.
- **Role**: includes `manage_users` and related admin permissions.
- **Teams**: not relevant for user management.
- **Admin flag**: `0` if `manage_users` alone is sufficient; `1` only if you genuinely need admin override.
- **Verify**: the user can `POST /api/v2/users` to create users, and the created users get the right initial role/team.
## Common pitfalls
A handful of patterns recur with API permissions.
- **Generating keys against admin users.** The compromise blast radius is enormous. Use dedicated, least-privileged integration users.
- **Forgetting that team membership filters the integration's view.** "Why does my integration see only some of the risks?" — usually the integration user isn't on the team that owns the missing risks.
- **Granting `admin = 1` to fix permission issues.** Diagnose the actual missing permission and grant that specifically; don't paper over with admin override.
- **Not creating a per-integration user.** Sharing one user across multiple integrations means rotating the key affects all integrations and audit attribution is ambiguous.
- **Granting permissions ad-hoc to individual users instead of defining roles.** Three integrations with the same permission profile should use the same role; otherwise role-management drift over time produces inconsistent integration behavior.
- **Not testing the integration's permissions before going live.** "It works for the developer's admin account; deploy to production" → first 403 in production is the integration first proving it lacks the actual permission.
- **Treating 403 as a transient error.** It's not; the user genuinely lacks the permission. Check permissions; don't add retry logic.
- **Forgetting that some endpoints require the user be on a specific team.** A risk endpoint may filter by team; a configuration endpoint may require admin. The endpoint's permission check is endpoint-specific.
- **Confusing read permissions with team filtering.** A user with `view_risks` permission *and* membership in the relevant team can see those risks; either alone isn't enough for cross-team visibility.
- **Granting permissions for hypothetical future operations.** "Just give it `manage_users` in case." No — give it what it needs now; expand when needed. Over-granting is a liability.
## Related
- [API Overview](https://support.simplerisk.com/kb/08-01-api-overview?hsLang=en)
- [Authentication and API Keys](https://support.simplerisk.com/kb/08-02-authentication-and-api-keys?hsLang=en)
- [API Key Management](https://support.simplerisk.com/kb/04-07-api-key-management?hsLang=en)
- [The Permission Model](https://support.simplerisk.com/kb/03-02-the-permission-model?hsLang=en)
- [Permission Reference](https://support.simplerisk.com/kb/03-03-permission-reference?hsLang=en)
- [Team-Based Segregation](https://support.simplerisk.com/kb/03-06-team-based-segregation?hsLang=en)
- [Managing Users, Teams, and Roles](https://support.simplerisk.com/kb/03-01-managing-users-teams-and-roles?hsLang=en)
- [FAQs](https://support.simplerisk.com/kb/faqs?hsLang=en)
- [SimpleRisk Extras](https://support.simplerisk.com/kb/simplerisk-extras?hsLang=en#main-content)
- [Vulnerability Management Extra](https://support.simplerisk.com/kb/simplerisk-extras?hsLang=en#vulnerability-management-extra)
- [Team Separation Extra](https://support.simplerisk.com/kb/simplerisk-extras?hsLang=en#team-separation-extra)
- [Import-Export Extra](https://support.simplerisk.com/kb/simplerisk-extras?hsLang=en#import-export-extra)
- [Administrator Guide](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#main-content)
- [00 About This Guide](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#00-about-this-guide)
- [01 Installation and Deployment](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#01-installation-and-deployment)
- [02 Upgrades and Maintenance](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#02-upgrades-and-maintenance)
- [03 Users and Permissions](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#03-users-and-permissions)
- [04 Authentication](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#04-authentication)
- [05 Customization](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#05-customization)
- [06 Configuring Risk and Compliance](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#06-configuring-risk-and-compliance)
- [07 Integrations](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#07-integrations)
- [08 The API](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#08-the-api)
- [09 Encryption and Data Security](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#09-encryption-and-data-security)
- [10 Workflows and Automation](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#10-workflows-and-automation)
- [11 Reporting and Auditing](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#11-reporting-and-auditing)
- [12 Operations](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#12-operations)
- [13 Reference](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#13-reference)
- [User Guide](https://support.simplerisk.com/kb/user-guide?hsLang=en#main-content)
- [00 Foundations of GRC](https://support.simplerisk.com/kb/user-guide?hsLang=en#00-foundations-of-grc)
- [01 Risk Management](https://support.simplerisk.com/kb/user-guide?hsLang=en#01-risk-management)
- [02 Compliance Management](https://support.simplerisk.com/kb/user-guide?hsLang=en#02-compliance-management)
- [03 Governance](https://support.simplerisk.com/kb/user-guide?hsLang=en#03-governance)
- [04 Asset and Data Inventory](https://support.simplerisk.com/kb/user-guide?hsLang=en#04-asset-and-data-inventory)
- [05 Threat and Vulnerability Management](https://support.simplerisk.com/kb/user-guide?hsLang=en#05-threat-and-vulnerability-management)
- [06 Assessments](https://support.simplerisk.com/kb/user-guide?hsLang=en#06-assessments)
- [07 Incident Management](https://support.simplerisk.com/kb/user-guide?hsLang=en#07-incident-management)
- [08 Audit and Reporting](https://support.simplerisk.com/kb/user-guide?hsLang=en#08-audit-and-reporting)
- [09 Day-to-Day SimpleRisk](https://support.simplerisk.com/kb/user-guide?hsLang=en#09-day-to-day-simplerisk)
- [10 Continuous Improvement](https://support.simplerisk.com/kb/user-guide?hsLang=en#10-continuous-improvement)
- [SimpleRisk User Guides](https://support.simplerisk.com/kb/simplerisk-user-guides?hsLang=en)
- [Troubleshooting](https://support.simplerisk.com/kb/troubleshooting?hsLang=en)
- [SimpleRisk Hosted](https://support.simplerisk.com/kb/simplerisk-hosted?hsLang=en)
- [How To videos](https://support.simplerisk.com/kb/how-to-videos?hsLang=en)
[](https://www.simplerisk.com)
Copyright © 2026, SimpleRisk, Inc.