https://authress.io/knowledge-base/assets/js/42bdb38c.9329a725.js

1"use strict";(self.webpackChunkAuthressKnowledgeBase=self.webpackChunkAuthressKnowledgeBase||[]).push([[5085],{3905:(e,t,r)=>{r.d(t,{Zo:()=>l,kt:()=>h});var s=r(67294);function n(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function o(e,t){var r=Object.keys(e);if(Object.getOwnPropertySymbols){var s=Object.getOwnPropertySymbols(e);t&&(s=s.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),r.push.apply(r,s)}return r}function a(e){for(var t=1;t<arguments.length;t++){var r=null!=arguments[t]?arguments[t]:{};t%2?o(Object(r),!0).forEach((function(t){n(e,t,r[t])})):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(r)):o(Object(r)).forEach((function(t){Object.defineProperty(e,t,Object.getOwnPropertyDescriptor(r,t))}))}return e}function i(e,t){if(null==e)return{};var r,s,n=function(e,t){if(null==e)return{};var r,s,n={},o=Object.keys(e);for(s=0;s<o.length;s++)r=o[s],t.indexOf(r)>=0||(n[r]=e[r]);return n}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(s=0;s<o.length;s++)r=o[s],t.indexOf(r)>=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(n[r]=e[r])}return n}var c=s.createContext({}),u=function(e){var t=s.useContext(c),r=t;return e&&(r="function"==typeof e?e(t):a(a({},t),e)),r},l=function(e){var t=u(e.components);return s.createElement(c.Provider,{value:t},e.children)},p={inlineCode:"code",wrapper:function(e){var t=e.children;return s.createElement(s.Fragment,{},t)}},d=s.forwardRef((function(e,t){var r=e.components,n=e.mdxType,o=e.originalType,c=e.parentName,l=i(e,["components","mdxType","originalType","parentName"]),d=u(r),h=n,m=d["".concat(c,".").concat(h)]||d[h]||p[h]||o;return r?s.createElement(m,a(a({ref:t},l),{},{components:r})):s.createElement(m,a({ref:t},l))}));function h(e,t){var r=arguments,n=t&&t.mdxType;if("string"==typeof e||n){var o=r.length,a=new Array(o);a[0]=d;var i={};for(var c in t)hasOwnProperty.call(t,c)&&(i[c]=t[c]);i.originalType=e,i.mdxType="string"==typeof e?e:n,a[1]=i;for(var u=2;u<o;u++)a[u]=r[u];return s.createElement.apply(null,a)}return s.createElement.apply(null,r)}d.displayName="MDXCreateElement"},47358:(e,t,r)=>{r.d(t,{Z:()=>k});var s=r(67294),n=r(52802),o=r(86010),a=r(39960),i=r(13919),c=r(95999);const u="cardContainer_S8oU",l="cardTitle_HoSo",p="cardDescription_c27F";function d(e){let{href:t,children:r}=e;return s.createElement(a.Z,{href:t,className:(0,o.Z)("card padding--lg",u)},r)}function h(e){let{href:t,icon:r,title:n,description:a}=e;return s.createElement(d,{href:t},s.createElement("h2",{className:(0,o.Z)("text--truncate",l),title:n},r," ",n),a&&s.createElement("p",{className:(0,o.Z)("text--truncate",p),title:a},a))}function m(e){var t;let{item:r}=e;const o=(0,n.Wl)(r);if(!o)return null;let a;try{const e=`${r.href.replace(/^\/knowledge-base\/docs\//,"")}/index`.replace("//","/");a=(0,n.xz)(e)}catch(i){}return s.createElement(h,{href:o,icon:"\ud83d\uddc3\ufe0f",title:r.label,description:r.description??(null==(t=a)?void 0:t.description)??(0,c.I)({message:"{count} items",id:"theme.docs.DocCard.categoryDescription",description:"The default description for a category card in the generated index about how many items this category includes"},{count:r.items.length})})}function g(e){let{item:t}=e;const r=(0,i.Z)(t.href)?"\ud83d\udcc4\ufe0f":"\ud83d\udd17",o=(0,n.xz)(t.docId??void 0);return s.createElement(h,{href:t.href,icon:r,title:t.label,description:t.description??(null==o?void 0:o.description)})}function f(e){let{item:t}=e;switch(t.type){case"link":return s.createElement(g,{item:t});case"category":return s.createElement(m,{item:t});default:throw new Error(`unknown item type ${JSON.stringify(t)}`)}}function y(e){let{className:t}=e;const r=(0,n.jA)();return s.createElement(k,{items:r.items,className:t})}function k(e){const{items:t}=e;if(!t)return s.createElement(y,e);const r=(0,n.MN)(t);return s.createElement("section",{className:"DocCardList"},r.map(((e,t)=>s.createElement("article",{key:t,className:"DocCardWrapper"},s.createElement(f,{item:e})))))}},67271:(e,t,r)=>{r.r(t),r.d(t,{assets:()=>u,contentTitle:()=>i,default:()=>d,frontMatter:()=>a,metadata:()=>c,toc:()=>l});var s=r(87462),n=(r(67294),r(3905)),o=r(47358);const a={slug:"/category/authorization",title:"Authorization"},i=void 0,c={unversionedId:"authorization/index",id:"authorization/index",title:"Authorization",description:"Authorization in Authress is how you grant users access to perform actions on resources. Performing user authorization checks requires three pieces:",source:"@site/docs/02-authorization/index.mdx",sourceDirName:"02-authorization",slug:"/category/authorization",permalink:"/knowledge-base/docs/category/authorization",draft:!1,editUrl:"https://gitlab.com/rhosys/authress-public-kb/knowledge-base/-/blob/main/docs/02-authorization/index.mdx",tags:[],version:"current",lastUpdatedAt:1772377859,formattedLastUpdatedAt:"Mar 1, 2026",frontMatter:{

1slug:"/category/authorization",title:"Authorization"},sidebar:"tutorialSidebar",previous:{title:"Billing and rate limiting",permalink:"/knowledge-base/docs/introduction/api-billing-caching"},next:{title:"Access records",permalink:"/knowledge-base/docs/authorization/access-records"}},u={},l=[{value:"Core Aspect: User roles",id:"core-aspect-user-roles",level:2},{value:"Core Aspect: Configuring user permissions",id:"core-aspect-configuring-user-permissions",level:2},{value:"Core Aspect: Authorization check",id:"core-aspect-authorization-check",level:2},{value:"Going Deeper: Authorization topics",id:"going-deeper-authorization-topics",level:2}],p={toc:l};function d(e){let{components:t,...a}=e;return(0,n.kt)("wrapper",(0,s.Z)({},p,a,{components:t,mdxType:"MDXLayout"}),(0,n.kt)("p",null,"Authorization in Authress is how you grant users access to perform actions on resources. Performing user authorization checks requires three pieces:"),(0,n.kt)("ul",null,(0,n.kt)("li",{parentName:"ul"},"User"),(0,n.kt)("li",{parentName:"ul"},"Permission"),(0,n.kt)("li",{parentName:"ul"},"Resource")),(0,n.kt)("p",null,"In Authress, a user has a permission to perform an action on a resource. This access is captured in Authress in an ",(0,n.kt)("a",{parentName:"p",href:"/knowledge-base/docs/authorization/access-records"},"Access Record"),". Access records govern all access in Authress. You create and manage access records for all permissions you want to assign to users. Additionally, Authress also creates access records at runtime when Authress releated resources are created, updated, and deleted."),(0,n.kt)("p",null,"The changes that are made to a user's or group's access is captured in the ",(0,n.kt)("a",{parentName:"p",href:"/knowledge-base/docs/account-management/aws-event-bridge-audit-trail"},"Authress Audit Trail"),"."),(0,n.kt)("p",null,"Verifying user authorization happens at runtime, where access records are used to verify access. Below is a high level guide to understanding the different core aspects of Authorization in Authress."),(0,n.kt)("admonition",{type:"success"},(0,n.kt)("p",{parentName:"admonition"},"Throughout the ",(0,n.kt)("a",{parentName:"p",href:"https://authress.io/app/#/"},"Management Portal"),", the ",(0,n.kt)("a",{parentName:"p",href:"https://authress.io/app/#/api"},"API"),", and the ",(0,n.kt)("a",{parentName:"p",href:"https://authress.io/app/#/api"},"SDKs"),", you will see references to a ",(0,n.kt)("inlineCode",{parentName:"p"},"User ID"),". User IDs can either be one from your existing Authentication system or generated by Authress. For Authress generated users you can convert an incoming request JWT to a user ID. For more information about doing that ",(0,n.kt)("strong",{parentName:"p"},"see ",(0,n.kt)("a",{parentName:"strong",href:"/knowledge-base/docs/authentication/validating-jwts#authress-user-ids-and-a-jwt-access-token-example"},"Verifying Authress JWTs")),".")),(0,n.kt)("h2",{id:"core-aspect-user-roles"},"Core Aspect: User roles"),(0,n.kt)("small",{className:"small"},(0,n.kt)("p",null,"  ",(0,n.kt)("em",{parentName:"p"},"See ",(0,n.kt)("a",{parentName:"em",href:"/knowledge-base/docs/authorization/permissions"},"Permissions and Roles")," for more information on how to use roles"))),(0,n.kt)("p",null,"Authress doesn\u2019t know how your software works, nor does it need to. But it does need to know about your permissions."),(0,n.kt)("p",null,"In Authress, permissions are grouped into roles. Think of roles as sets of permissions that are often granted together. For example, a document owner may be able to \u201cread\u201d, \u201cwrite\u201d, and \u201cdelete\u201d the document, while a reviewer would be only able to \u201cread\u201d and \u201csuggest\u201d."),(0,n.kt)("p",null,"You may already have a model of your user personas and typical actions associated with each of them - these will likely correspond to your roles. If your model is incomplete, or you\u2019re not ready to think about it yet, you may use the built-in roles and expand them later as your software evolves. You can define your roles, as well as see the built-in ones in ",(0,n.kt)("a",{parentName:"p",href:"https://authress.io/app/#/setup?focus=roles"},"Management Portal"),"."),(0,n.kt)("p",null,(0,n.kt)("img",{alt:"Authress comes with some pre-built roles",src:r(24108).Z,width:"924",height:"372"})),(0,n.kt)("p",null,"Later on, you\u2019ll be applying these roles to specific resources and users through the access records, described below."),(0,n.kt)("h2",{id:"core-aspect-configuring-user-permissions"},"Core Aspect: Configuring user permissions"),(0,n.kt)("small",{className:"small"},(0,n.kt)("p",null,"  ",(0,n.kt)("em",{parentName:"p"},"See ",(0,n.kt)("a",{parentName:"em",href:"/knowledge-base/docs/authorization/access-records"},"Access Records")," for more information on assigning permissions"))),(0,n.kt)("p",null,"Authress authorizes your users based on the permissions you configure. This is done through access records. Authress does not need to know about your users directly. Instead, access is granted to your users by their ",(0,n.kt)("inlineCode",{parentName:"p"},"User ID"),". To migrate to Authress or start granting permissions, access records will be created that contain the relevant ",(0,n.kt)("inlineCode",{parentName:"p"},"userId"),", the ",(0,n.kt)("inlineCode",{parentName:"p"},"role"),", and the ",(0,n.kt)("inlineCode",{parentName:"p"},"resources"),". If you are interested in support to help migrate to Authress or want to set up a POC, please reach out to the ",(0,n.kt)("a",{parentName:"p",href:"https://authress.io/app/#/support"},"development team"),"."),(0,n.kt)("p",null,"Whenever a new resource is created in your software (e.g., user creates a new document), you create a new access record in Authress by calling ",(0,n.kt)("a",{parentName:"p",href:"https://authress.io/app/#post-/v1/records"},"respective API")," and specifying the roles.\nYou can also do this manually in ",(0,n.kt)("a",{parentName:"p",href:"https://authress.io/app/#/manage?focus=records"},"Management Portal"),". Here is an example code snippet to do that:"),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-js",metastring:'title="Create access record example"',title:'"Create',access:!0,record:!0,'example"':!0},"import { AuthressClient } from '@authress/sdk';\n\nconst authressClient = new AuthressClient()\n\n[POST('/v1/resources')]\nfunction createResource(request) {\n  await authressClient.userPermissions.authorizeUser(request.userId, `resources/${resourceId}`, 'UPDATE');\n  // Create new resource\n  // ...\n  const newRecord = {\n    recordId: `rec_resources_${resourceId}`,\n    users: [{ userId: request.userId }],\n    statements: [{\n        roles: ['Authress:Owner'],\n        resources: [{ resourceUri: `resources/${resourceId}` }]\n    }]\n  };\n  await authressClient.accessRecords.createRecord(newRecord);\n  return OK;\n}\n")),(0,n.kt)("h2",{id:"core-aspect-authorization-check"},"Core Aspect: Authorization check"),(0,n.kt)("p",null,"Now that everything is set up, each time your software needs to decide whether the user should be allowed to perform certain actions on a given resource, you simply make an API call to Authress. You\u2019ll get back either a 200 (meaning user has permissions) or 404 (meaning user doesn\u2019t have permissions)."),(0,n.kt)("p",null,"Here is an example using the NodeJS ",(0,n.kt)("a",{parentName:"p",href:"https://authress.io/app/#/api"},"Authress SDK")," to quickly perform an authorization check."),(0,n.kt)("pre",null,(0,n.kt)("code",{parentName:"pre",className:"language-js",metastring:'title="Verify user authorization"',title:'"Verify',user:!0,'authorization"':!0},"import { AuthressClient } from '@authress/sdk';\n\nconst authressClient = new AuthressClient()\n\n[GET('/v1/resources/{resourceId}')]\nfunction getResource(request) {\n  // highlight-start\n  await authressClient.userPermissions.authorizeUser(request.userId, `resources/${resourceId}`, 'READ');\n  // highlight-end\n  // Application route code\n  return OK;\n}\n")),(0,n.kt)("p",null,"Take a look at the full ",(0,n.kt)("a",{parentName:"p",href:"https://authress.io/app/#/api"},"API documentation")," to see what else is possible or see these authorization resources:"),(0,n.kt)("h2",{id:"going-deeper

1-authorization-topics"},"Going Deeper: Authorization topics"),(0,n.kt)(o.Z,{mdxType:"DocCardList"}))}d.isMDXComponent=!0},24108:(e,t,r)=>{r.d(t,{Z:()=>s});const s=r.p+"assets/images/built-in-roles-6a3548db0a4d4e9d2510e414f9ee627d.png"}}]);