{"id":19510007,"url":"https://github.com/permify/go-role","last_synced_at":"2025-04-26T03:32:08.891Z","repository":{"id":38779131,"uuid":"467958410","full_name":"Permify/go-role","owner":"Permify","description":"Open source RBAC library. Associate users with roles and permissions.","archived":false,"fork":false,"pushed_at":"2022-10-21T12:27:26.000Z","size":83,"stargazers_count":210,"open_issues_count":2,"forks_count":19,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-04T07:35:15.017Z","etag":null,"topics":["access-control","golang","golang-library","gorm","open-source","permission","permissions","rbac","role-based-access-control"],"latest_commit_sha":null,"homepage":"https://permify.co/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Permify.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null}},"created_at":"2022-03-09T14:21:47.000Z","updated_at":"2025-02-22T11:54:21.000Z","dependencies_parsed_at":"2022-07-14T22:17:00.092Z","dependency_job_id":null,"html_url":"https://github.com/Permify/go-role","commit_stats":null,"previous_names":["permify/permify-gorm"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Permify%2Fgo-role","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Permify%2Fgo-role/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Permify%2Fgo-role/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Permify%2Fgo-role/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Permify","download_url":"https://codeload.github.com/Permify/go-role/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250926863,"owners_count":21509050,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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","golang","golang-library","gorm","open-source","permission","permissions","rbac","role-based-access-control"],"created_at":"2024-11-10T23:14:10.476Z","updated_at":"2025-04-26T03:32:07.848Z","avatar_url":"https://github.com/Permify.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\u003ch1 align=\"center\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/Permify/permify/master/assets/permify-logo.svg\" alt=\"Permify logo\" width=\"336px\" /\u003e\u003cbr /\u003e\n\u003c/h1\u003e\n\n[![Go Reference](https://pkg.go.dev/badge/github.com/Permify/go-role.svg)](https://pkg.go.dev/github.com/Permify/go-role)\n[![Go Report Card](https://goreportcard.com/badge/github.com/Permify/go-role)](https://goreportcard.com/report/github.com/Permify/go-role)\n![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/Permify/go-role)\n![GitHub](https://img.shields.io/github/license/Permify/go-role)\n[![Twitter Follow](https://img.shields.io/twitter/follow/GetPermify?style=social)](https://twitter.com/GetPermify)\n\n## Associate users with roles and permissions\n\nThis package allows you to manage user permissions and roles in your database.\n\n## 👇 Setup\n\nInstall\n\n```shell\ngo get github.com/Permify/go-role\n```\n\nRun All Tests\n\n```shell\ngo test ./...\n```\n\nGet the database driver for gorm that you will be using\n\n```shell\n# mysql \ngo get gorm.io/driver/mysql \n# or postgres\ngo get gorm.io/driver/postgres\n# or sqlite\ngo get gorm.io/driver/sqlite\n# or sqlserver\ngo get gorm.io/driver/sqlserver\n# or clickhouse\ngo get gorm.io/driver/clickhouse\n```\n\nImport permify.\n\n```go\nimport permify `github.com/Permify/go-role`\n```\n\nInitialize the new Permify.\n\n```go\n// initialize the database. (you can use all gorm's supported databases)\ndb, _ := gorm.Open(mysql.Open(\"user:password@tcp(host:3306)/db?charset=utf8\u0026parseTime=True\u0026loc=Local\"), \u0026gorm.Config{})\n\n// New initializer for Permify\n// If migration is true, it generate all tables in the database if they don't exist.\npermify, _ := permify.New(permify.Options{\n\tMigrate: true,\n\tDB: db,\n})\n```\n\n## 🚲 Basic Usage\n\nThis package allows users to be associated with permissions and roles. Each role is associated with multiple permissions.\n\n```go\n// CreateRole create new role.\n// Name parameter is converted to guard name. example: senior $#% associate -\u003e senior-associate.\n// If a role with the same name has been created before, it will not create it again. (FirstOrCreate)\n// First parameter is role name, second parameter is role description.\nerr := permify.CreateRole(\"admin\", \"role description\")\n\n// CreatePermission create new permission.\n// Name parameter is converted to guard name. example: create $#% contact -\u003e create-contact.\n// If a permission with the same name has been created before, it will not create it again. (FirstOrCreate)\nerr := permify.CreatePermission(\"edit user details\", \"\")\n```\n\nPermissions can be added to a role using AddPermissionsToRole method in different ways:\n\n```go\n// first parameter is role id\nerr := permify.AddPermissionsToRole(1, \"edit user details\")\n// or\nerr := permify.AddPermissionsToRole(\"admin\", []string{\"edit user details\", \"create contact\"})\n// or\nerr := permify.AddPermissionsToRole(\"admin\", []uint{1, 3})\n```\n\nWith using these methods you can remove and overwrite permissions:\n\n```go\n// overwrites the permissions of the role according to the permission names or ids.\nerr := permify.ReplacePermissionsToRole(\"admin\", []string{\"edit user details\", \"create contact\"})\n\n// remove permissions from role according to the permission names or ids.\nerr := permify.RemovePermissionsFromRole(\"admin\", []string{\"edit user details\"})\n```\n\nBasic fetch queries:\n\n```go\n// Fetch all the roles. (with pagination option).\n// If withPermissions is true, it will preload the permissions to the role.\n// If pagination is nil, it returns without paging.\nroles, totalCount, err := permify.GetAllRoles(options.RoleOption{\n\tWithPermissions: true,\n\tPagination: \u0026utils.Pagination{\n\t\tPage: 1,\n\t\tLimit: 1,\n\t},\n})\n\n// without paging.\nroles, totalCount, err := permify.GetAllRoles(options.RoleOption{\n    WithPermissions: false,\n})\n\n// The data returned is a collection of roles.\n// Collections provides a fluent convenient wrapper for working with arrays of data.\nfmt.Println(roles.IDs())\nfmt.Println(roles.Names())\nfmt.Println(roles.Permissions().Names())\n\n// Fetch all permissions of the user that come with direct and roles.\npermissions, _ := permify.GetAllPermissionsOfUser(1)\n\n// Fetch all direct permissions of the user. (with pagination option)\npermissions, totalCount, err := permify.GetDirectPermissionsOfUser(1, options.PermissionOption{\n    Pagination: \u0026utils.Pagination{\n        Page: 1,\n        Limit: 10,\n    },\n})\n```\n\nControls\n\n```go\n// does the role or any of the roles have given permission?\ncan, err := permify.RoleHasPermission(\"admin\", \"edit user details\")\n\n// does the role or roles have any of the given permissions?\ncan, err := permify.RoleHasAnyPermissions([]string{\"admin\", \"manager\"}, []string{\"edit user details\", \"create contact\"})\n\n// does the role or roles have all the given permissions?\ncan, err := permify.RoleHasAllPermissions(\"admin\", []string{\"edit user details\", \"create contact\"})\n\n// does the user have the given permission? (including the permissions of the roles)\ncan, err := permify.UserHasPermission(1, \"edit user details\")\n\n// does the user have the given permission? (not including the permissions of the roles)\ncan, err := permify.UserHasDirectPermission(1, \"edit user details\")\n\n// does the user have any of the given permissions? (including the permissions of the roles)\ncan, err := permify.UserHasAnyPermissions(1, []uint{1, 2})\n\n// does the user have all the given roles?\ncan, err := permify.UserHasAllRoles(1, []string{\"admin\", \"manager\"})\n\n// does the user have any of the given roles?\ncan, err := permify.UserHasAnyRoles(1, []string{\"admin\", \"manager\"})\n```\n\n\n## 🚘 Using permissions via roles\n\n### Adding Role\n\nAdd roles to user according to the role names or ids:\n\n```go\n// add one role to user\nerr := permify.AddRolesToUser(1, \"admin\")\n\n// you can also add multiple roles at once\nerr := permify.AddRolesToUser(1, []string{\"admin\", \"manager\"})\n// or\nerr := permify.AddRolesToUser(1, []uint{1,2})\n```\n\nReplace the roles of the user according to the role names or ids:\n\n```go\n// remove all user roles and add admin role\nerr := permify.ReplaceRolesToUser(1, \"admin\")\n\n// you can also replace multiple roles at once\nerr := permify.ReplaceRolesToUser(1, []string{\"admin\", \"manager\"})\n// or\nerr := permify.RemoveRolesFromUser(1, []uint{1,2})\n```\n\nRemove the roles of the user according to the role names or ids:\n\n```go\n// remove one role to user\nerr := permify.RemoveRolesFromUser(1, \"admin\")\n\n// you can also remove multiple roles at once\nerr := permify.RemoveRolesFromUser(1, []string{\"admin\", \"manager\"})\n// or\nerr := permify.RemoveRolesFromUser(1, []uint{1,2})\n```\n\nControl Roles\n\n```go\n// does the user have the given role?\ncan, err := permify.UserHasRole(1, \"admin\")\n\n// does the user have all the given roles?\ncan, err := permify.UserHasAllRoles(1, []string{\"admin\", \"manager\"})\n\n// does the user have any of the given roles?\ncan, err := permify.UserHasAnyRoles(1, []string{\"admin\", \"manager\"})\n```\n\nGet User's Roles\n\n```go\nroles, totalCount, err := permify.GetRolesOfUser(1, options.RoleOption{\n    WithPermissions: true, // preload role's permissions\n    Pagination: \u0026utils.Pagination{\n        Page: 1,\n        Limit: 1,\n    },\n})\n\n// the data returned is a collection of roles. \n// Collections provides a fluent convenient wrapper for working with arrays of data.\nfmt.Println(roles.IDs())\nfmt.Println(roles.Names())\nfmt.Println(roles.Len())\nfmt.Println(roles.Permissions().Names())\n```\n\nAdd Permissions to Roles\n\n```go\n// add one permission to role\n// first parameter can be role name or id, second parameter can be permission name(s) or id(s).\nerr := permify.AddPermissionsToRole(\"admin\", \"edit contact details\")\n\n// you can also add multiple permissions at once\nerr := permify.AddPermissionsToRole(\"admin\", []string{\"edit contact details\", \"delete user\"})\n// or\nerr := permify.AddPermissionsToRole(\"admin\", []uint{1, 2})\n```\n\nRemove Permissions from Roles\n\n```go\n// remove one permission to role\nerr := permify.RemovePermissionsFromRole(\"admin\", \"edit contact details\")\n\n// you can also add multiple permissions at once\nerr := permify.RemovePermissionsFromRole(\"admin\", []string{\"edit contact details\", \"delete user\"})\n// or\nerr := permify.RemovePermissionsFromRole(\"admin\", []uint{1, 2})\n```\n\nControl Role's Permissions\n\n```go\n// does the role or any of the roles have given permission?\ncan, err := permify.RoleHasPermission([]string{\"admin\", \"manager\"}, \"edit contact details\")\n\n// does the role or roles have all the given permissions?\ncan, err := permify.RoleHasAllPermissions(\"admin\", []string{\"edit contact details\", \"delete contact\"})\n\n// does the role or roles have any of the given permissions?\ncan, err := permify.RoleHasAnyPermissions(1, []string{\"edit contact details\", \"delete contact\"})\n```\n\nGet Role's Permissions\n\n```go\npermissions, totalCount, err := permify.GetPermissionsOfRoles([]string{\"admin\", \"manager\"}, options.PermissionOption{\n    Pagination: \u0026utils.Pagination{\n        Page: 1,\n        Limit: 1,\n    },\n})\n\n// the data returned is a collection of permissions. \n// Collections provides a fluent convenient wrapper for working with arrays of data.\nfmt.Println(permissions.IDs())\nfmt.Println(permissions.Names())\nfmt.Println(permissions.Len())\n```\n\n## 🚤 Direct Permissions\n\n### Adding Direct Permissions\n\nAdd direct permission or permissions to user according to the permission names or ids.\n\n```go\n// add one permission to user\nerr := permify.AddPermissionsToUser(1, \"edit contact details\")\n\n// you can also add multiple permissions at once\nerr := permify.AddPermissionsToUser(1, []string{\"edit contact details\", \"create contact\"})\n// or\nerr := permify.AddPermissionsToUser(1, []uint{1,2})\n```\n\nRemove the roles of the user according to the role names or ids:\n\n```go\n// remove one role to user\nerr := permify.RemovePermissionsFromUser(1, \"edit contact details\")\n\n// you can also remove multiple permissions at once\nerr := permify.RemovePermissionsFromUser(1, []string{\"edit contact details\", \"create contact\"})\n// or\nerr := permify.RemovePermissionsFromUser(1, []uint{1,2})\n```\n\nControl Permissions\n\n```go\n// ALL PERMISSIONS\n\n// does the user have the given permission? (including the permissions of the roles)\ncan, err := permify.UserHasPermission(1, \"edit contact details\")\n\n// does the user have all the given permissions? (including the permissions of the roles)\ncan, err := permify.UserHasAllPermissions(1, []string{\"edit contact details\", \"delete contact\"})\n\n// does the user have any of the given permissions? (including the permissions of the roles).\ncan, err := permify.UserHasAnyPermissions(1, []string{\"edit contact details\", \"delete contact\"})\n\n// DIRECT PERMISSIONS\n\n// does the user have the given permission? (not including the permissions of the roles)\ncan, err := permify.UserHasDirectPermission(1, \"edit contact details\")\n\n// does the user have all the given permissions? (not including the permissions of the roles)\ncan, err := permify.UserHasAllDirectPermissions(1, []string{\"edit contact details\", \"delete contact\"})\n\n// does the user have any of the given permissions? (not including the permissions of the roles)\ncan, err := permify.UserHasAnyDirectPermissions(1, []string{\"edit contact details\", \"delete contact\"})\n```\n\nGet User's All Permissions\n\n```go\npermissions, err := permify.GetAllPermissionsOfUser(1)\n\n// the data returned is a collection of permissions. \n// Collections provides a fluent convenient wrapper for working with arrays of data.\nfmt.Println(permissions.IDs())\nfmt.Println(permissions.Names())\nfmt.Println(permissions.Len())\n```\n\nGet User's Direct Permissions\n\n```go\npermissions, totalCount, err := permify.GetDirectPermissionsOfUser(1, options.PermissionOption{\n    Pagination: \u0026utils.Pagination{\n        Page:  1,\n        Limit: 10,\n    },\n})\n\n// the data returned is a collection of permissions.\n// Collections provides a fluent convenient wrapper for working with arrays of data.\nfmt.Println(permissions.IDs())\nfmt.Println(permissions.Names())\nfmt.Println(permissions.Len())\n```\n\n## 🚀 Using your user model\n\nYou can create the relationships between the user and the role and permissions in this manner. In this way:\n\n- You can manage user preloads\n- You can create foreign key between users and pivot tables (user_roles, user_permissions).\n\n```go\nimport (\n    \"gorm.io/gorm\"\n    models `github.com/Permify/go-role/models`\n)\n\ntype User struct {\n    gorm.Model\n    Name string\n\n    // permify\n    Roles       []models.Role       `gorm:\"many2many:user_roles;constraint:OnUpdate:CASCADE,OnDelete:CASCADE\"`\n    Permissions []models.Permission `gorm:\"many2many:user_permissions;constraint:OnUpdate:CASCADE,OnDelete:CASCADE\"`\n}\n```\n\n## ⁉️ Error Handling\n\n### ErrRecordNotFound\n\nYou can use error handling in the same way as gorm. for example:\n\n```go\n// check if returns RecordNotFound error\npermission, err := permify.GetPermission(1)\nif errors.Is(err, gorm.ErrRecordNotFound) {\n\t// record not found\n}\n```\n\n### Errors\n\n[Errors List](https://github.com/go-gorm/gorm/blob/master/errors.go)\n\n\nStargazers\n-----------\n\n[![Stargazers repo roster for @Permify/go-role](https://reporoster.com/stars/Permify/go-role)](https://github.com/Permify/go-role/stargazers)\n\n\n## Community \u0026 Support\nJoin our [Discord channel](https://discord.gg/MJbUjwskdH) for issues, feature requests, feedbacks or anything else. We love to talk about authorization and access control :heart:\n\n\u003cp align=\"left\"\u003e\n\u003ca href=\"https://discord.gg/MJbUjwskdH\"\u003e\n \u003cimg height=\"70px\" width=\"70px\" alt=\"permify | Discord\" src=\"https://user-images.githubusercontent.com/39353278/187209316-3d01a799-c51b-4eaa-8f52-168047078a14.png\" /\u003e\n\u003c/a\u003e\n\u003ca href=\"https://twitter.com/GetPermify\"\u003e\n  \u003cimg height=\"70px\" width=\"70px\" alt=\"permify | Twitter\" src=\"https://user-images.githubusercontent.com/39353278/187209323-23f14261-d406-420d-80eb-1aa707a71043.png\"/\u003e\n\u003c/a\u003e\n\u003ca href=\"https://www.linkedin.com/company/permifyco\"\u003e\n  \u003cimg height=\"70px\" width=\"70px\" alt=\"permify | Linkedin\" src=\"https://user-images.githubusercontent.com/39353278/187209321-03293a24-6f63-4321-b362-b0fc89fdd879.png\" /\u003e\n\u003c/a\u003e\n\u003c/p\u003e\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpermify%2Fgo-role","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpermify%2Fgo-role","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpermify%2Fgo-role/lists"}