{"id":13521267,"url":"https://github.com/infratographer/permissions-api","last_synced_at":"2026-01-21T01:30:58.010Z","repository":{"id":65339156,"uuid":"567438887","full_name":"infratographer/permissions-api","owner":"infratographer","description":"Permissions management service over SpiceDB","archived":false,"fork":false,"pushed_at":"2026-01-14T22:40:27.000Z","size":1317,"stargazers_count":10,"open_issues_count":26,"forks_count":12,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-01-15T04:54:17.088Z","etag":null,"topics":["access-control","authorization","iam","permissions","rbac","spicedb"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/infratographer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-11-17T19:48:02.000Z","updated_at":"2025-04-29T07:09:46.000Z","dependencies_parsed_at":"2023-10-03T00:18:44.420Z","dependency_job_id":"4e2b4fe9-03d2-4fff-8778-469d41a9755e","html_url":"https://github.com/infratographer/permissions-api","commit_stats":null,"previous_names":[],"tags_count":41,"template":false,"template_full_name":null,"purl":"pkg:github/infratographer/permissions-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infratographer%2Fpermissions-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infratographer%2Fpermissions-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infratographer%2Fpermissions-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infratographer%2Fpermissions-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/infratographer","download_url":"https://codeload.github.com/infratographer/permissions-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infratographer%2Fpermissions-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28621571,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T23:49:58.628Z","status":"ssl_error","status_checked_at":"2026-01-20T23:47:29.996Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["access-control","authorization","iam","permissions","rbac","spicedb"],"created_at":"2024-08-01T06:00:31.938Z","updated_at":"2026-01-21T01:30:57.993Z","avatar_url":"https://github.com/infratographer.png","language":"Go","funding_links":[],"categories":["Integrations"],"sub_categories":["Third-party Integrations"],"readme":"![logo](https://github.com/infratographer/website/blob/main/source/theme/assets/pictures/logo.jpg?raw=true)\n# permissions-api - Permissions management service\n\nHello, and welcome to permissions-api! permissions-api is a service designed for checking and managing permissions on resources in the Infratographer ecosystem.\n\npermissions-api is made up of two components:\n\n* A policy decision endpoint for making permissions checks\n* A management API for resources necessary to make decisions\n\nTo get started using permissions-api, see the [Usage](#usage) section of this README.\n\n## Concepts\n\npermissions-api is designed to answer the following question: Does the given _subject_ have permission to perform the requested _action_ on the requested _resource_?\n\nPermission is granted by the assignment of roles to subjects.\n\nThe concepts necessary to accomplish this are described in this section.\n\n### Resource\n\nA resource is any uniquely identifiable thing in the Infratographer ecosystem. Resources have types and are identified using Prefixed IDs in permissions-api. For example, the Prefixed ID `loadbal-hWV_xTSoYqIkXXWyK6eco` corresponds to a resource of type `loadbalancer`.\n\n### Subject\n\nA subject is any resource that can be granted permission to perform some action. A subject may be a user, an OAuth client, a server instance, or any other resource.\n\n### Relationship\n\nA relationship is a named link between a resource and a subject (another resource). Resources in permissions-api are defined entirely in terms of their relationships. For example, a load balancer and tenant might be related to each other using a relationship with the name `tenant`, where the resource is a load balancer and the subject is a tenant.\n\n### Action\n\nAn action is a verb that describes something that can be done to a resource (e.g., \"update\"). Actions map to permissions in SpiceDB, and are scoped to and named based on resources. For example, an action called `update` scoped to the `loadbalancer` resource is referred to as `loadbalancer_update`.\n\nWhen making authorization decisions, permissions-api walks the graph of known relationships to determine whether a path exists between the resource and subject, and whether that path meets the constraints of the action's corresponding SpiceDB permission.\n\n### Role\n\nA role is a collection of actions that are allowed to be performed on a resource. A role like `loadbalancer_readonly` might allow the actions `loadbalancer_get` and `loadbalancer_list`, for example.\n\n### Role assignment\n\nA role assignment is a relationship that binds a subject to a role. This is how a subject is granted access to a resource.\n\n## Usage\n\npermissions-api is a Go service. To build it, you can use `make build` to build a Go binary. Configuration is done using environment variables and/or a YAML config file. An example config is available at [`permissions-api.example.yaml`](./permissions-api.example.yaml), and an example environment file is available at [`.devcontainer/.env`](./.devcontainer/.env).\n\n### Generating SpiceDB schema\n\nTo generate a SpiceDB schema based on the resource types defined in permissions-api, use the `schema` command:\n\n```\n$ ./permissions-api schema --dry-run --config permissions-api.example.yaml\n```\n\nOmit the `--dry-run` flag to apply the schema to your SpiceDB server.\n\n### Running a server\n\nTo run the permissions-api server, use the `server` command:\n\n```\n$ ./permissions-api server --config permissions-api.example.yaml\n```\n\n### Generating access tokens\n\npermissions-api requests are authenticated using JWT access tokens. If you are using the provided [dev container](#development), permissions-api is already configured to accept JWTs from the included [mock-oauth2-server][mock-oauth2-server] service. A UI to manually create access tokens is available at http://localhost:8081/default/debugger. Tokens must be configured with a \"scope\" value in the UI set to `openid permissions-api` (which maps to an audience in the JWT of `permissions-api`) and a Prefixed ID (ex: `idntusr-0xqwVtYKHjjuLfjSItHLU`).\n\n[mock-oauth2-server]: https://github.com/navikt/mock-oauth2-server\n\n### Creating relationships\n\nResources are defined in terms of their relationships to other resources using the `/relationships` API endpoint. Using curl, one can create a relationship `tenant` between two tenants like so:\n\n```\n$ curl --oauth2-bearer \"$AUTH_TOKEN\" \\\n    -d '{\"relationships\": [{\"relation\": \"tenant\", \"subject_id\": \"tnntten-OJrD-JdCFThZiRgqk6vs6\"}]}' \\\n    http://localhost:7602/api/v1/resources/tnntten-MCR3xIIMWfVpVM22w82NZ/relationships\n```\n\n### Creating roles\n\nRoles are created using the `/roles` API endpoint. For example, the following curl command creates a role scoped to a tenant that allows the `loadbalancer_create` action:\n\n```\n$ curl --oauth2-bearer \"$AUTH_TOKEN\" \\\n    -d '{\"actions\": [\"loadbalancer_create\"]}' \\\n    http://localhost:7602/api/v1/resources/tnntten-MCR3xIIMWfVpVM22w82NZ/roles\n```\n\n### Assigning roles to subjects\n\nRoles are assigned to subjects using the `/assignments` API endpoint. The curl command below will assign the subject with the given ID to the given role:\n\n```\n$ curl --oauth2-bearer \"$AUTH_TOKEN\" \\\n    -d '{\"subject_id\": \"idntusr-0xqwVtYKHjjuLfjSItHLU\"}' \\\n    http://localhost:7602/api/v1/roles/permrol-XqGKCT8L5CikBuIpbFQEt/assignments\n```\n\n### Checking permissions\n\nThe `/allow` API endpoint is used to check whether the authenticated subject in the given bearer token has permission to perform the requested action on the given resource. The following example checks to see whether a subject can perform the `loadbalancer_create` operation on a tenant:\n\n```\n$ curl --oauth2-bearer \"$AUTH_TOKEN\" \\\n    http://localhost:7602/api/v1/allow?action=loadbalancer_create\u0026resource=tnntten-MCR3xIIMWfVpVM22w82NZ\n```\n\n## Development\n\nidentity-api includes a [dev container][dev-container] for facilitating service development. Using the dev container is not required, but provides a consistent environment for all contributors as well as a few perks like:\n\n* [gopls][gopls] integration out of the box\n* Host SSH auth socket mount\n* Git support\n* Auxiliary services (SpiceDB, CRDB, etc)\n\nTo get started, you can use either [VS Code][vs-code] or the official [CLI][cli].\n\n[dev-container]: https://containers.dev/\n[gopls]: https://pkg.go.dev/golang.org/x/tools/gopls\n[vs-code]: https://code.visualstudio.com/docs/devcontainers/containers\n[cli]: https://github.com/devcontainers/cli\n\n### Spanner Emulator\n\nTo develop on Spanner DB emulator:\n\n1. edit `.devcontainer/devcontainer.json` and use `spanner.docker-compose.yml`\n\n### Manually setting up SSH agent forwarding\n\nThe provided dev container listens for SSH connections on port 2222 and bind mounts `~/.ssh/authorized_keys` from the host to facilitate SSH. In order to perform Git operations (i.e., committing code in the container), you will need to enable SSH agent forwarding from your machine to the dev container. While VS Code handles this automatically, for other editors you will need to set this up manually.\n\nTo do so, update your `~/.ssh/config` to support agent forwarding. The following config snippet assumes the existence of a remote host used for development and uses it to make permissions-api reachable at the host `permissions-api-devcontainer`:\n\n```\nHost permissions-api-devcontainer\n  ProxyJump YOUR_HOST_HERE\n  Port 2224\n  User vscode\n  ForwardAgent yes\n\nHost YOUR_HOST_HERE\n  User YOUR_USER_HERE\n  ForwardAgent yes\n```\n\nSee the man page for `ssh_config` for more information on what these options do.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finfratographer%2Fpermissions-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finfratographer%2Fpermissions-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finfratographer%2Fpermissions-api/lists"}