1"use strict";(globalThis.webpackChunkorki_docs=globalThis.webpackChunkorki_docs||[]).push([[5538],{6145(e,n,s){s.d(n,{R:()=>o,x:()=>l});var t=s(7140);const i={},r=t.createContext(i);function o(e){const n=t.useContext(r);return t.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function l(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:o(e.components),t.createElement(r.Provider,{value:n},e.children)}},8143(e,n,s){s.r(n),s.d(n,{assets:()=>a,contentTitle:()=>l,default:()=>h,frontMatter:()=>o,metadata:()=>t,toc:()=>d});const t=JSON.parse('{"id":"settings/tokens","title":"API Tokens","description":"API tokens provide programmatic API access to Orki. They let external systems interact with your tenant without requiring a human user \u2014 perfect for integrations, automations, and custom workflows.","source":"@site/docs/settings/tokens.md","sourceDirName":"settings","slug":"/settings/tokens","permalink":"/docs/settings/tokens","draft":false,"unlisted":false,"tags":[],"version":"current","sidebarPosition":7,"frontMatter":{"sidebar_position":7},"sidebar":"tutorialSidebar","previous":{"title":"Billing","permalink":"/docs/settings/billing"},"next":{"title":"Webhooks","permalink":"/docs/settings/webhooks"}}');var i=s(5656),r=s(6145);const o={sidebar_position:7},l="API Tokens",a={},d=[{value:"Creating a Token",id:"creating-a-token",level:2},{value:"Permission Modes",id:"permission-modes",level:3},{value:"Credentials",id:"credentials",level:3},{value:"Managing Tokens",id:"managing-tokens",level:2},{value:"Using the Token",id:"using-the-token",level:2},{value:"API Documentation",id:"api-documentation",level:3},{value:"Webhooks",id:"webhooks",level:2},{value:"Next Steps",id:"next-steps",level:2}];function c(e){const n={a:"a",admonition:"admonition",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",hr:"hr",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,r.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(n.header,{children:(0,i.jsx)(n.h1,{id:"api-tokens",children:"API Tokens"})}),"\n",(0,i.jsx)(n.p,{children:"API tokens provide programmatic API access to Orki. They let external systems interact with your tenant without requiring a human user \u2014 perfect for integrations, automations, and custom workflows."}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Path:"})," Settings > API Tokens"]}),"\n",(0,i.jsx)(n.hr,{}),"\n",(0,i.jsx)(n.h2,{id:"creating-a-token",children:"Creating a Token"}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["Go to ",(0,i.jsx)(n.strong,{children:"Settings > API Tokens"})]}),"\n",(0,i.jsxs)(n.li,{children:["Click ",(0,i.jsx)(n.strong,{children:'"Create Token"'})]}),"\n",(0,i.jsxs)(n.li,{children:["Fill in the details:","\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Username"})," \u2014 a name to identify this token (lowercase letters, numbers, and hyphens only; 3\u201350 characters)"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Description"})," \u2014 what this token is used for"]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["Choose a ",(0,i.jsx)(n.strong,{children:"Permission Mode"})," (see below)"]}),"\n"]}),"\n",(0,i.jsx)(n.h3,{id:"permission-modes",children:"Permission Modes"}),"\n",(0,i.jsxs)(n.table,{children:[(0,i.jsx)(n.thead,{children:(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.th,{children:"Mode"}),(0,i.jsx)(n.th,{children:"Description"})]})}),(0,i.jsxs)(n.tbody,{children:[(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.strong,{children:"Role"})}),(0,i.jsx)(n.td,{children:"Pick one of the built-in roles: Super Admin, Admin, Marketer, Service Agent, or Analyst"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.strong,{children:"Custom"})}),(0,i.jsx)(n.td,{children:"Granular per-feature permission matrix \u2014 select exactly which features and actions to allow"})]})]})]}),"\n",(0,i.jsx)(n.h3,{id:"credentials",children:"Credentials"}),"\n",(0,i.jsxs)(n.p,{children:["After creation, a ",(0,i.jsx)(n.strong,{children:"Token Created"})," dialog shows:"]}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Client ID"})," \u2014 in the form ",(0,i.jsx)(n.code,{children:"svc-<tenant>-<username>"})]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Client Secret"})," \u2014 shown ",(0,i.jsx)(n.strong,{children:"once only"})]}),"\n",(0,i.jsxs)(n.li,{children:["A ready-made ",(0,i.jsx)(n.strong,{children:"usage example"}),": a ",(0,i.jsx)(n.code,{children:"client_credentials"})," curl for the token endpoint you can copy as-is"]}),"\n"]}),"\n",(0,i.jsx)(n.admonition,{type:"warning",children:(0,i.jsx)(n.p,{children:"Save the client secret now \u2014 it won't be shown again. If lost, you must regenerate it."})}),"\n",(0,i.jsx)(n.hr,{}),"\n",(0,i.jsx)(n.h2,{id:"managing-tokens",children:"Managing Tokens"}),"\n",(0,i.jsxs)(n.table,{children:[(0,i.jsx)(n.thead,{children:(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.th,{children:"Action"}),(0,i.jsx)(n.th,{children:"Description"})]})}),(0,i.jsxs)(n.tbody,{children:[(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.strong,{children:"Edit Permissions"})}),(0,i.jsxs)(n.td,{children:["Change the permission mode, role, or custom scopes, and manage ",(0,i.jsx)(n.strong,{children:"Linked Customers"}),". The username is ",(0,i.jsx)(n.strong,{children:"not"})," editable."]})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.strong,{children:"Regenerate Secret"})}),(0,i.jsxs)(n.td,{children:["Generate a new ",(0,i.jsx)(n.code,{children:"client_secret"})," (invalidates the old one)"]})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.strong,{children:"Activate / Deactivate"})}),(0,i.jsx)(n.td,{children:"Temporarily disable the token without deleting it"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.strong,{children:"Delete"})}),(0,i.jsx)(n.td,{children:"Permanently remove the token"})]})]})]}),"\n",(0,i.jsx)(n.hr,{}),"\n",(0,i.jsx)(n.h2,{id:"using-the-token",children:"Using the Token"}),"\n",(0,i.jsxs)(n.p,{children:["Authenticate via Keycloak token exchange using the ",(0,i.jsx)(n.code,{children:"client_credentials"})," grant type:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:'curl -X POST "https://auth.orki.ai/realms/orki/protocol/openid-connect/token" \\\n -H "Content-Type: application/x-www-form-urlencoded" \\\n -d "grant_type=client_credentials" \\\n -d "client_id=YOUR_CLIENT_ID" \\\n -d "client_secret=YOUR_CLIENT_SECRET"\n'})}),"\n",(0,i.jsxs)(n.p,{children:["The response includes an ",(0,i.jsx)(n.code,{children:"access_token"}),". Use it in the ",(0,i.jsx)(n.code,{children:"Authorization"})," header for all API calls:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:'curl -X GET "https://api.orki.ai/gateway/api/v1/tenants/{tenantId}/customers" \\\n -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\n'})}),"\n",(0,i.jsx)(n.h3,{id:"api-documentation",children:"API Documentation"}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.strong,{children:"API Documentation"})," card on this page links to the interactive (Swagger) docs for the ",(0,i.jsx)(n.strong,{children:"Gateway"}),", ",(0,i.jsx)(n.strong,{children:"Marketing"}),", ",(0,i.jsx)(n.strong,{children:"Products"}),", and ",(0,i.jsx)(n.strong,{children:"KB Website"})," APIs. Use these docs to explore available endpoints and request/response formats."]}),"\n",(0,i.jsx)(n.admonition,{type:"tip",children:(0,i.jsx)(n.p,{children:"Create separate tokens for different integrations so you can revoke access independently without affecting other systems."})}),"\n",(0,i.jsx)(n.hr,{}),"\n",(0,i.jsx)(n.h2,{id:"webhooks",children:"Webhooks"}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.a,{href:"./webhooks",children:"Webhooks"})," are configured on this same page \u2014 the webhook card sits below the tokens list. Use them to receive real-time event notifications on your server."]}),"\n",(0,i.jsxs)(n.p,{children:["Combined with ",(0,i.jsx)(n.a,{href:"./system-events",children:"System Events"})," \u2014 which your backend fires ",(0,i.jsx)(n.strong,{children:"into"})," Orki using these tokens \u2014 this page is the hub for two-way integration with your systems."]}),"\n",(0,i.jsx)(n.hr,{}),"\n",(0,i.jsx)(n.h2,{id:"next-steps",children:"Next Steps"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.a,{href:"./webhooks",children:"Webhooks"})," \u2014 Receive real-time notifications when events happen in Orki"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.a,{href:"./system-events",children:"System Events"})," \u2014 Fire structured events at a chat using these tokens"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.a,{href:"./team",children:"Team Management"})," \u2014 Manage team members and roles"]}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(c,{...e})}):c(e)}}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.