---
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)

[![SimpleRisk logo of a man walking a tight rope](https://support.simplerisk.com/hs-fs/hubfs/simplerisk_logo_long_small-4.png?width=377&height=72&name=simplerisk_logo_long_small-4.png)](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 apply exactly as they would in the browser, and so do team filters when the Team-Based Separation Extra is active.

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 the Team-Based Separation Extra is active and your integration needs to see risks across multiple teams (e.g., a centralized dashboard), the integration user needs team memberships covering those teams. (Without the Extra, Core doesn't filter by team.) For "see everything" integrations, either:

- Add the user to every team, OR
- Set the user's `admin` flag to `1` (which bypasses the Extra's 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.

Some refusals answer **401 Unauthorized** instead, and three different situations produce one. Only the first is about your key:

- **"Unauthenticated Access. Please log in or provide a key to use the SimpleRisk API.":** No key was sent, or SimpleRisk doesn't recognize the one that was. Re-authenticating is the right response.
- **"You don't have permission for this action.":** The key is valid. The account failed the general access check that gates the application as a whole, which usually means the account is disabled or has lost its access permission.
- **"Unauthorized Access. The authenticated user does not have proper permissions.":** The key is valid. This is an ordinary permission refusal on an endpoint that predates the 403 convention.

Branch on the message, not on the code by itself. An integration that reads every 401 as an expired key will re-authenticate against the second and third rows and fail the same way every time.

Denials from the Incident Management and Vulnerability Management endpoints used to arrive as a redirect carrying an empty body, or as an empty HTTP 200 that a client could easily record as success. They now return the same JSON envelope as the rest of the API. If you built a workaround for either shape, you can retire it.

### 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:

- **A specific record or file the caller isn't entitled to: a questionnaire attachment, a risk belonging to another team, the compliance test-result risk closure:** `warning`
- **A named permission refused on an API or AJAX request:** `notice`
- **A named permission refused on an ordinary page request, which redirects to the login page:** `info`
- **An admin-only endpoint refusing a non-admin:** nothing

The split between the middle two rows is deliberate. An API refusal stops an integration dead and deserves an operator's attention, while the page-level equivalent is someone clicking something they don't have rights to, which happens all day and rarely means anything. Endpoints that answer 401 through the API's shared unauthorized-access helper write no log entry at all, so the HTTP response is the only trace you get. If you're troubleshooting a denial you can't find in the log, raise `logging_notice` (or `logging_info` for the page-level case) 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 when the Team-Based Separation Extra is active).
- **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.** With the Team-Based Separation Extra active, 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.** With the Team-Based Separation Extra active, a user with `view_risks` permission *and* membership in the relevant team (or another enabled visibility path) can see those risks; the permission alone isn't enough. Without the Extra, the permission alone is enough.
- **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 Separation](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)
    - [11 Business Continuity and Disaster Recovery](https://support.simplerisk.com/kb/user-guide?hsLang=en#11-business-continuity-and-disaster-recovery)
- [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)

[![favicon-1](https://support.simplerisk.com/hs-fs/hubfs/favicon-1.png?width=35&height=35&name=favicon-1.png "favicon-1")](https://www.simplerisk.com)

<https://www.facebook.com/simplerisk/> <https://www.twitter.com/simpleriskfree/> <https://www.linkedin.com/company/simplerisk/>

Copyright © 2026, SimpleRisk, Inc.