1"use strict";(self.webpackChunkthinkfree_developers_docs=self.webpackChunkthinkfree_developers_docs||[]).push([[8219],{508(e,n,s){s.r(n),s.d(n,{assets:()=>l,contentTitle:()=>c,default:()=>o,frontMatter:()=>t,metadata:()=>d,toc:()=>a});const d=JSON.parse('{"id":"management/api/admin","title":"Admin API","description":"Manage accounts, quotas, activation, MFA, and the license for one tenant, and configure sign-in, branding, access, sharing, and SMTP.","source":"@site/docs/management/api/admin.md","sourceDirName":"management/api","slug":"/management/api/admin","permalink":"/docs/management/api/admin","draft":false,"unlisted":false,"tags":[],"version":"current","sidebarPosition":17,"frontMatter":{"title":"Admin API","sidebar_label":"Admin","sidebar_position":17,"description":"Manage accounts, quotas, activation, MFA, and the license for one tenant, and configure sign-in, branding, access, sharing, and SMTP.","keywords":["Document Management SDK","admin API","user management","license","tenant settings"]},"sidebar":"managementSidebar","previous":{"title":"Users","permalink":"/docs/management/api/users"},"next":{"title":"Audit logs","permalink":"/docs/management/api/audit-logs"}}');var r=s(4848),i=s(8453);const t={title:"Admin API",sidebar_label:"Admin",sidebar_position:17,description:"Manage accounts, quotas, activation, MFA, and the license for one tenant, and configure sign-in, branding, access, sharing, and SMTP.",keywords:["Document Management SDK","admin API","user management","license","tenant settings"]},c="Admin API",l={},a=[{value:"Base URL and authorization",id:"base-url-and-authorization",level:2},{value:"Pagination",id:"pagination",level:2},{value:"Create an account",id:"create-an-account",level:2},{value:"Read an account",id:"read-an-account",level:2},{value:"Update an account",id:"update-an-account",level:2},{value:"List administrators",id:"list-administrators",level:2},{value:"Set an account password",id:"set-an-account-password",level:2},{value:"Activate and deactivate",id:"activate-and-deactivate",level:2},{value:"Mark an account for deletion",id:"mark-an-account-for-deletion",level:2},{value:"Reset MFA",id:"reset-mfa",level:2},{value:"Import accounts from CSV",id:"import-accounts-from-csv",level:2},{value:"Read a user's profile image",id:"read-a-users-profile-image",level:2},{value:"List user accounts",id:"list-user-accounts",level:2},{value:"Search accounts for API Key issuance",id:"search-accounts-for-api-key-issuance",level:2},{value:"Read storage usage",id:"read-storage-usage",level:2},{value:"Read an account's security log",id:"read-an-accounts-security-log",level:2},{value:"Check the status of several accounts",id:"check-the-status-of-several-accounts",level:2},{value:"Create and update accounts in bulk",id:"create-and-update-accounts-in-bulk",level:2},{value:"Delete an account immediately",id:"delete-an-account-immediately",level:2},{value:"Accounts pending deletion",id:"accounts-pending-deletion",level:2},{value:"License",id:"license",level:2},{value:"Register a license",id:"register-a-license",level:3},{value:"Read the license",id:"read-the-license",level:3},{value:"Read license status",id:"read-license-status",level:3},{value:"Sign-in settings",id:"sign-in-settings",level:2},{value:"Branding",id:"branding",level:2},{value:"Access restriction",id:"access-restriction",level:2},{value:"Share settings",id:"share-settings",level:2},{value:"SMTP",id:"smtp",level:2},{value:"System configuration",id:"system-configuration",level:2},{value:"General",id:"general",level:3},{value:"Office",id:"office",level:3},{value:"Storage",id:"storage",level:3},{value:"Feature toggles",id:"feature-toggles",level:3},{value:"File size limit",id:"file-size-limit",level:3},{value:"Share data check",id:"share-data-check",level:3},{value:"Errors",id:"errors",level:2}];function h(e){const n={a:"a",admonition:"admonition",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",mdxAdmonitionTitle:"mdxAdmonitionTitle",p:"p",pre:"pre",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",...(0,i.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(n.header,{children:(0,r.jsx)(n.h1,{id:"admin-api",children:"Admin API"})}),"\n",(0,r.jsxs)(n.p,{children:["Administrative operations scoped to one tenant: creating and maintaining accounts, controlling activation, resetting\nMFA, managing the license, and configuring how the tenant behaves. For operations across tenants, see\n",(0,r.jsx)(n.a,{href:"/docs/management/api/super-admin",children:"Super Admin"}),". The tenant's audit trail has its own page, ",(0,r.jsx)(n.a,{href:"/docs/management/api/audit-logs",children:"Audit logs"}),"."]}),"\n",(0,r.jsx)(n.h2,{id:"base-url-and-authorization",children:"Base URL and authorization"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-http",children:"/api/external/v1/admins\n"})}),"\n",(0,r.jsxs)(n.p,{children:["These endpoints require an API Key issued to an account holding the ",(0,r.jsx)(n.code,{children:"ADMIN"})," role. A super administrator's key also\npasses. Two endpoints are exceptions, noted where they appear."]}),"\n",(0,r.jsx)(n.admonition,{title:"Scope is not checked here",type:"warning",children:(0,r.jsxs)(n.p,{children:["Authorization for ",(0,r.jsx)(n.code,{children:"/admins/**"})," is by role alone. The API Key's scope is not examined, so a key holding only ",(0,r.jsx)(n.code,{children:"api:read"}),"\ncan create accounts, change quotas, deactivate users, import CSV, and register a license. Treat any admin key as a\nfull-privilege credential regardless of the scope it was issued with."]})}),"\n",(0,r.jsx)(n.admonition,{title:"The single-account endpoint cannot create administrators",type:"note",children:(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.code,{children:"POST /admins"})," authenticated by an external API Key may only create accounts with ",(0,r.jsx)(n.code,{children:"rt"})," of ",(0,r.jsx)(n.code,{children:"USER"}),". Asking for ",(0,r.jsx)(n.code,{children:"ADMIN"})," is\nrejected with ",(0,r.jsx)(n.code,{children:"USER_013"}),". Note that ",(0,r.jsx)(n.a,{href:"#create-and-update-accounts-in-bulk",children:"bulk account import"})," does not apply the same\nrestriction - see the warning there."]})}),"\n",(0,r.jsxs)(n.p,{children:["Every operation is limited to the caller's own tenant. An endpoint that takes a ",(0,r.jsx)(n.code,{children:"userSeq"})," returns ",(0,r.jsx)(n.code,{children:"USER_005"})," for a\n",(0,r.jsx)(n.code,{children:"userSeq"})," in another tenant, the same response as for one that does not exist, so account existence is not disclosed."]}),"\n",(0,r.jsx)(n.h2,{id:"pagination",children:"Pagination"}),"\n",(0,r.jsxs)(n.p,{children:["Admin listings use cursor pagination: send ",(0,r.jsx)(n.code,{children:"ps"})," for the page size and ",(0,r.jsx)(n.code,{children:"ci"})," as the last ",(0,r.jsx)(n.code,{children:"userSeq"})," of the previous page.\n",(0,r.jsx)(n.code,{children:"nextCursor"})," and ",(0,r.jsx)(n.code,{children:"hasNext"})," are omitted from the response when they have no value."]}),"\n",(0,r.jsx)(n.h2,{id:"create-an-account",children:"Create an account"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-http",children:"POST /api/external/v1/admins\n"})}),"\n",(0,r.jsxs)(n.p,{children:["Send as ",(0,r.jsx)(n.code,{children:"multipart/form-data"}),"."]}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Parameter"}),(0,r.jsx)(n.th,{children:"Type"}),(0,r.jsx)(n.th,{children:"Required"}),(0,r.jsx)(n.th,{children:"Description"})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"ui"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsx)(n.td,{children:"Account id, an email address, up to 25 characters"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"encPwd"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsx)(n.td,{children:"Password, 8 to 64 characters, with at least one uppercase letter, lowercase letter, digit, and symbol"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"un"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsx)(n.td,{children:"Display name, up to 20 characters"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"tq"})}),(0,r.jsx)(n.td,{children:"long"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsx)(n.td,{children:"Storage allowance in bytes"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"rt"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsxs)(n.td,{children:["Role; an external key may only send ",(0,r.jsx)(n.code,{children:"USER"})]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"pif"})}),(0,r.jsx)(n.td,{children:"file"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsx)(n.td,{children:"Profile image"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"ct"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsx)(n.td,{children:"Country dialing code without the plus sign, up to 4 characters"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"pn"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsx)(n.td,{children:"Phone number without separators, up to 20 characters"})]})]})]}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.code,{children:"ct"})," and ",(0,r.jsx)(n.code,{children:"pn"})," must be sent together or both left out; sending one alone returns ",(0,r.jsx)(n.code,{children:"USER_027"}),"."]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",metastring:'title="Create account"',children:'curl -X POST "https://drive.example.com/api/external/v1/admins" \\\n -H "Authorization: Bearer replace-with-your-TENANTADMIN-API-KEY" \\\n -F "[email protected]" \\\n -F "encPwd=User1234!" \\\n -F "un=First user" \\\n -F "tq=1000000000" \\\n -F "rt=USER"\n'})}),"\n",(0,r.jsxs)(n.p,{children:["Returns the new ",(0,r.jsx)(n.code,{children:"userSeq"}),". A malformed email returns ",(0,r.jsx)(n.code,{children:"USER_002"}),", a duplicate returns ",(0,r.jsx)(n.code,{children:"USER_004"}),", and a request that\nexceeds the licensed seats or available storage returns ",(0,r.jsx)(n.code,{children:"USER_013"})," or ",(0,r.jsx)(n.code,{children:"QUOTA_004"}),"."]}),"\n",(0,r.jsx)(n.h2,{id:"read-an-account",children:"Read an account"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-http",children:"GET /api/external/v1/admins/{userSeq}\n"})}),"\n",(0,r.jsx)(n.p,{children:"Returns the account with its quota, role, status, phone, MFA state, and registration and update history. Dates are\nformatted strings rather than ISO instants."}),"\n",(0,r.jsxs)(n.admonition,{type:"note",children:[(0,r.jsxs)(n.mdxAdmonitionTitle,{children:[(0,r.jsx)(n.code,{children:"isActive"})," is deprecated"]}),(0,r.jsxs)(n.p,{children:["It is kept for backward compatibility. Read ",(0,r.jsx)(n.code,{children:"status"})," instead."]})]}),"\n",(0,r.jsx)(n.h2,{id:"update-an-account",children:"Update an account"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-http",children:"PATCH /api/external/v1/admins/{userSeq}\n"})}),"\n",(0,r.jsxs)(n.p,{children:["Send as ",(0,r.jsx)(n.code,{children:"multipart/form-data"}),"."]}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Parameter"}),(0,r.jsx)(n.th,{children:"Type"}),(0,r.jsx)(n.th,{children:"Required"}),(0,r.jsx)(n.th,{children:"Description"})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"un"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsx)(n.td,{children:"Display name, up to 20 characters"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"tq"})}),(0,r.jsx)(n.td,{children:"long"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsx)(n.td,{children:"Storage allowance in bytes"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"ct"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsxs)(n.td,{children:["Country dialing code; send with ",(0,r.jsx)(n.code,{children:"pn"})," or omit both"]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"pn"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsxs)(n.td,{children:["Phone number; send with ",(0,r.jsx)(n.code,{children:"ct"})," or omit both"]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"pif"})}),(0,r.jsx)(n.td,{children:"file"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsx)(n.td,{children:"Profile image"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"dpi"})}),(0,r.jsx)(n.td,{children:"boolean"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsxs)(n.td,{children:["Delete the existing profile image; defaults to ",(0,r.jsx)(n.code,{children:"false"})]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"sk"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsx)(n.td,{children:"Storage key"})]})]})]}),"\n",(0,r.jsxs)(n.p,{children:["A quota below what the account already uses is rejected with ",(0,r.jsx)(n.code,{children:"USER_014"}),"."]}),"\n",(0,r.jsx)(n.h2,{id:"list-administrators",children:"List administrators"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-http",children:"GET /api/external/v1/admins\n"})}),"\n",(0,r.jsx)(n.p,{children:"Lists administrator accounts in the caller's tenant, excluding ordinary users."}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Parameter"}),(0,r.jsx)(n.th,{children:"Type"}),(0,r.jsx)(n.th,{children:"Required"}),(0,r.jsx)(n.th,{children:"Description"})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"ps"})}),(0,r.jsx)(n.td,{children:"integer"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsxs)(n.td,{children:["Page size, minimum ",(0,r.jsx)(n.code,{children:"1"})]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"ci"})}),(0,r.jsx)(n.td,{children:"long"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsxs)(n.td,{children:["Cursor - the last ",(0,r.jsx)(n.code,{children:"userSeq"})," of the previous page"]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"s"})}),(0,r.jsx)(n.td,{children:"enum"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsxs)(n.td,{children:["Filter by state - ",(0,r.jsx)(n.code,{children:"active"})," or ",(0,r.jsx)(n.code,{children:"inactive"}),", case-insensitive"]})]})]})]}),"\n",(0,r.jsxs)(n.p,{children:["Any other value for ",(0,r.jsx)(n.code,{children:"s"})," returns ",(0,r.jsx)(n.code,{children:"USER_019"}),"."]}),"\n",(0,r.jsx)(n.h2,{id:"set-an-account-password",children:"Set an account password"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-http",children:"PATCH /api/external/v1/admins/{userSeq}/password\n"})}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Parameter"}),(0,r.jsx)(n.th,{children:"Type"}),(0,r.jsx)(n.th,{children:"Required"}),(0,r.jsx)(n.th,{children:"Description"})]})}),(0,r.jsx)(n.tbody,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"newPwd"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsx)(n.td,{children:"New password, 8 to 64 characters, with at least one uppercase letter, lowercase letter, digit, and symbol"})]})})]}),"\n",(0,r.jsx)(n.p,{children:"The current password is not required, so this
1sets a password rather than changing one."}),"\n",(0,r.jsx)(n.h2,{id:"activate-and-deactivate",children:"Activate and deactivate"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-http",children:"PATCH /api/external/v1/admins/{userSeq}/activate\nPATCH /api/external/v1/admins/{userSeq}/deactivate\n"})}),"\n",(0,r.jsxs)(n.p,{children:["A failed activation returns ",(0,r.jsx)(n.code,{children:"USER_017"})," and a failed deactivation returns ",(0,r.jsx)(n.code,{children:"USER_018"}),". Neither your own account nor the\ntenant's default administrator can be deactivated; attempting it returns ",(0,r.jsx)(n.code,{children:"USER_011"}),"."]}),"\n",(0,r.jsx)(n.h2,{id:"mark-an-account-for-deletion",children:"Mark an account for deletion"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-http",children:"PATCH /api/external/v1/admins/{userSeq}/withdraw\n"})}),"\n",(0,r.jsxs)(n.p,{children:["Moves the account to a pending-delete state rather than removing it. Your own account and the default administrator\ncannot be targeted, which returns ",(0,r.jsx)(n.code,{children:"USER_012"}),". A failure to queue the deletion returns ",(0,r.jsx)(n.code,{children:"USER_016"}),". See\n",(0,r.jsx)(n.a,{href:"#accounts-pending-deletion",children:"accounts pending deletion"})," for what happens next."]}),"\n",(0,r.jsx)(n.h2,{id:"reset-mfa",children:"Reset MFA"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-http",children:"PATCH /api/external/v1/admins/users/{userSeq}/mfa/reset\n"})}),"\n",(0,r.jsxs)(n.p,{children:["Clears the target account's multi-factor setup so the user can enrol again. The action is written to the audit log as\n",(0,r.jsx)(n.code,{children:"USER_TWOFACTOR_RESET"}),". A failure returns ",(0,r.jsx)(n.code,{children:"USER_022"}),"."]}),"\n",(0,r.jsx)(n.h2,{id:"import-accounts-from-csv",children:"Import accounts from CSV"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-http",children:"GET /api/external/v1/admins/import/csv/sample\nPOST /api/external/v1/admins/import/csv\n"})}),"\n",(0,r.jsx)(n.p,{children:"Download the sample first; it defines the column layout the import expects."}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Parameter"}),(0,r.jsx)(n.th,{children:"Type"}),(0,r.jsx)(n.th,{children:"Required"}),(0,r.jsx)(n.th,{children:"Description"})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"file"})}),(0,r.jsx)(n.td,{children:"file"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsx)(n.td,{children:"CSV file in the sample's format"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"se"})}),(0,r.jsx)(n.td,{children:"boolean"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsx)(n.td,{children:"Send a welcome email to each created account"})]})]})]}),"\n",(0,r.jsxs)(n.p,{children:["A fully successful import returns ",(0,r.jsx)(n.code,{children:"insertCount"}),"."]}),"\n",(0,r.jsx)(n.admonition,{title:"A partial failure returns CSV, not JSON",type:"caution",children:(0,r.jsxs)(n.p,{children:["If any row fails - a duplicate account id, a seat or quota overrun, or a parse error - the response is HTTP 400 with a\n",(0,r.jsx)(n.code,{children:"text/csv"})," body rather than the JSON envelope. The returned file repeats the original columns and adds the reason each\nrow failed. Check ",(0,r.jsx)(n.code,{children:"Content-Type"})," before parsing the response as JSON."]})}),"\n",(0,r.jsx)(n.h2,{id:"read-a-users-profile-image",children:"Read a user's profile image"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-http",children:"GET /api/external/v1/users/{userSeq}/profile-image\n"})}),"\n",(0,r.jsxs)(n.p,{children:["This one endpoint sits under ",(0,r.jsx)(n.code,{children:"/users"})," rather than ",(0,r.jsx)(n.code,{children:"/admins"}),", so the role rule does not apply to it and the ordinary\nscope check does instead. A key with ",(0,r.jsx)(n.code,{children:"api:read"})," or ",(0,r.jsx)(n.code,{children:"api:write"}
1)," and no administrator role can call it."]}),"\n",(0,r.jsx)(n.admonition,{title:"No tenant boundary on this endpoint",type:"warning",children:(0,r.jsxs)(n.p,{children:["Unlike every other endpoint on this page, this one does not restrict the lookup to the caller's tenant. A ",(0,r.jsx)(n.code,{children:"userSeq"}),"\nbelonging to a different tenant returns that user's profile image rather than ",(0,r.jsx)(n.code,{children:"USER_005"}),". Do not rely on it to confirm\ntenant membership, and consider it when deciding who may reach it."]})}),"\n",(0,r.jsxs)(n.p,{children:["An account with no profile image returns ",(0,r.jsx)(n.code,{children:"USER_008"}),"."]}),"\n",(0,r.jsx)(n.h2,{id:"list-user-accounts",children:"List user accounts"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-http",children:"GET /api/external/v1/admins/users\n"})}),"\n",(0,r.jsxs)(n.p,{children:["Lists accounts with the ",(0,r.jsx)(n.code,{children:"USER"})," role in the caller's tenant. Administrator and super administrator accounts are always\nexcluded; use ",(0,r.jsx)(n.a,{href:"#list-administrators",children:"List administrators"})," for those."]}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Parameter"}),(0,r.jsx)(n.th,{children:"Type"}),(0,r.jsx)(n.th,{children:"Required"}),(0,r.jsx)(n.th,{children:"Description"})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"ps"})}),(0,r.jsx)(n.td,{children:"integer"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsxs)(n.td,{children:["Page size, minimum ",(0,r.jsx)(n.code,{children:"1"})]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"ci"})}),(0,r.jsx)(n.td,{children:"long"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsxs)(n.td,{children:["Cursor - the last ",(0,r.jsx)(n.code,{children:"userSeq"})," of the previous page"]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"s"})}),(0,r.jsx)(n.td,{children:"enum"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsxs)(n.td,{children:["Filter by state - ",(0,r.jsx)(n.code,{children:"ACTIVE"})," or ",(0,r.jsx)(n.code,{children:"INACTIVE"}),"; any other value returns ",(0,r.jsx)(n.code,{children:"USER_019"})]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"u"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsx)(n.td,{children:"Partial match against the account id"})]})]})]}),"\n",(0,r.jsxs)(n.p,{children:["Omitting ",(0,r.jsx)(n.code,{children:"s"})," returns the default visible states, leaving out deleted and pending-delete accounts."]}),"\n",(0,r.jsx)(n.h2,{id:"search-accounts-for-api-key-issuance",children:"Search accounts for API Key issuance"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-http",children:"GET /api/external/v1/admins/users/search\n"})}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Parameter"}),(0,r.jsx)(n.th,{children:"Type"}),(0,r.jsx)(n.th,{children:"Required"}),(0,r.jsx)(n.th,{children:"Description"})]})}),(0,r.jsx)(n.tbody,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"sk"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsx)(n.td,{children:"Search keyword matched against account id or display name"})]})})]}),"\n",(0,r.jsxs)(n.p,{children:["Only accounts with the ",(0,r.jsx)(n.code,{children:"USER"})," role and ",(0,r.jsx)(n.code,{children:"ACTIVE"})," status are returned. Other roles and states never appear, which is why\nthis endpoint suits choosing the account an API Key will be issued to."]}),"\n",(0,r.jsx)(n.h2,{id:"read-storage-usage",children:"Read storage usage"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-http",children:"GET /api/external/v1/admins/users/{userSeq}/storage-usage\n"})}),"\n",(0,r.jsx)(n.p,{children:"Breaks an account's consumption into its parts."}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Field"}),(0,r.jsx)(n.th,{children:"Type"}),(0,r.jsx)(n.th,{children:"Meaning"})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"totalQuotaBytes"})}),(0,r.jsx)(n.td,{children:"long"}),(0,r.jsx)(n.td,{children:"Storage allowance"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"totalUsedBytes"})}),(0,r.jsx)(n.td,{children:"long"}),(0,r.jsx)(n.td,{children:"Total consumed"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"liveUsedBytes"})}),(0,r.jsx)(n.td,{children:"long"}),(0,r.jsx)(n.td,{children:"Consumed by current files"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"versionUsedBytes"})}),(0,r.jsx)(n.td,{children:"long"}),(0,r.jsx)(n.td,{children:"Consumed by version history"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"trashUsedBytes"})}),(0,r.jsx)(n.td,{children:"long"}),(0,r.jsx)(n.td,{children:"Consumed by items in the trash"})]})]})]}),"\n",(0,r.jsx)(n.p,{children:"Emptying the trash or deleting version history reclaims the last two."}),"\n",(0,r.jsx)(n.h2,{id:"read-an-accounts-security-log",children:"Read an account's security log"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-http",children:"GET /api/external/v1/admins/users/{userSeq}/log\n"})}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Parameter"}),(0,r.jsx)(n.th,{children:"Type"}),(0,r.jsx)(n.th,{children:"Required"}),(0,r.jsx)(n.th,{children:"Description"})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"ps"})}),(0,r.jsx)(n.td,{children:"integer"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsx)(n.td,{children:"Number of entries to return"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"ci"})}),(0,r.jsx)(n.td,{children:"long"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsxs)(n.td,{children:["Cursor - the last ",(0,r.jsx)(n.code,{children:"userLogSeq"})," of the previous page"]})]})]})]}),"\n",(0,r.jsxs)(n.p,{children:["Entries carry ",(0,r.jsx)(n.code,{children:"activityType"}),", ",(0,r.jsx)(n.code,{children:"ipAddress"}),", ",(0,r.jsx)(n.code,{children:"region"}),", ",(0,r.jsx)(n.code,{children:"registerDate"}),", and ",(0,r.jsx)(n.code,{children:"actorType"}),", which says whether the user\nperformed the action themselves or an administrator did it on their behalf."]}),"\n",(0,r.jsx)(n.h2,{id:"check-the-status-of-several-accounts",children:"Check the status of several accounts"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-http",children:"POST /api/external/v1/admins/users/bulk-status\n"})}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Parameter"}),(0,r.jsx)(n.th,{children:"Type"}),(0,r.jsx)(n.th,{children:"Required"}),(0,r.jsx)(n.th,{children:"Description"})]})}),(0,r.jsx)(n.tbody,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"userIds"})}),(0,r.jsx)(n.td,{children:"array"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsx)(n.td,{children:"Account ids to look up; must not be empty"})]})})]}),"\n",(0,r.jsxs)(n.p,{children:["Returns ",(0,r.jsx)(n.code,{children:"userSeq"}),", ",(0,r.jsx)(n.code,{children:"userId"}),", and ",(0,r.jsx)(n.code,{children:"status"})," for each match."]}),"\n",(0,r.jsx)(n.admonition,{title:"Unknown ids are dropped silently",type:"note",children:(0,r.jsx)(n.p,{children:"An id that does not exist in the caller's tenant is left out of the result with no per-item error. Compare the returned\nlist against what you sent rather than assuming every id was resolved."})}),"\n",(0,r.jsx)(n.h2,{id:"create-and-update-accounts-in-bulk",children:"Create and update accounts in bulk"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-http",children:"POST /api/external/v1/admins/users/bulk\n"})}),"\n",(0,r.jsxs)(n.p,{children:["Creates and updates accounts in one request. Each entry with no ",(0,r.jsx)(n.code,{children:"us"})," is created; each entry with a ",(0,r.jsx)(n.code,{children:"us"})," is updated. The\nHTTP status is always 200 whether or not anything was created."]}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Parameter"}),(0,r.jsx)(n.th,{children:"Type"}),(0,r.jsx)(n.th,{children:"Required"}),(0,r.jsx)(n.th,{children:"Description"})]})}),(0,r.jsx)(n.tbody,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"users"})}),(0,r.jsx)(n.td,{children:"array"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsx)(n.td,{children:"Accounts to create or update; must not be empty"})]})})]}),"\n",(0,r.jsx)(n.p,{children:"Each entry takes:"}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Field"}),(0,r.jsx)(n.th,{children:"Type"}),(0,r.jsx)(n.th,{children:"Required"}),(0,r.jsx)(n.th,{children:"Description"})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"us"})}),(0,r.jsx)(n.td,{children:"integer"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsx)(n.td,{children:"Account seq; omit to create, supply to update"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"ui"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsx)(n.td,{children:"Account id, up to 25 characters; required when creating"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"encPwd"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsx)(n.td,{children:"Password, 8 to 64 characters with at least one uppercase letter, lowercase letter, digit, and symbol; required when creating"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"un"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsx)(n.td,{children:"Display name, up to 20 characters"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"tq"})}),(0,r.jsx)(n.td,{children:"long"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsx)(n.td,{children:"Storage allowance in bytes; cannot be reduced below current usage"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"rt"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsx)(n.td,{children:"Role; required when creating"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"ct"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsxs)(n.td,{children:["Country dialing code; send with ",(0,r.jsx)(n.code,{children:"pn"})," or omit both"]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"pn"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsxs)(n.td,{children:["Phone number; send with ",(0,r.jsx)(n.code,{children:"ct"})," or omit both"]})]})]})]}),"\n",(0,r.jsxs)(n.p,{children:["The response reports ",(0,r.jsx)(n.code,{children:"insertedCount"}),", ",(0,r.jsx)(n.code,{children:"updatedCount"}),", and the ",(0,r.jsx)(n.code,{children:"userId"})," and ",(0,r.jsx)(n.code,{children:"userSeq"})," of each created account."]}),"\n",(0,r.jsx)(n.admonition,{title:"This endpoint can create administrators",type:"warning",children:(0,r.jsxs)(n.p,{children:["Unlike ",(0,r.jsx)(n.code,{children:"POST /admins"}),", this one does not restrict ",(0,r.jsx)(n.code,{children:"rt"}),". ",(0,r.jsx)(n.code,{children:"ADMIN"})," and ",(0,r.jsx)(n.code,{children:"SUPER_ADMIN"})," are accepted and the accounts are\ncreated with those roles, so any admin API Key that reaches this endpoint can mint new administrator accounts. Restrict\nwhich of your callers can use it, and validate ",(0,r.jsx)(n.code,{children:"rt"})," yourself before forwarding a request. A value that is not a known\nrole is not rejected cleanly either - it fails with HTTP 500."]})}),"\n",(0,r.jsxs)(n.p,{children:["A missing required field on create returns ",(0,r.jsx)(n.code,{children:"USER_026"}),", a password that fails the pattern returns ",(0,r.jsx)(n.code,{children:"USER_001"}),", a\nduplicate account id returns ",(0,r.jsx)(n.code,{children:"USER_004"}),", and reducing a quota below current usage returns ",(0,r.jsx)(n.code,{children:"USER_014"}),"."]}),"\n",(0,r.jsx)(n.h2,{id:"delete-an-account-immediately",children:"Delete an account immediately"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-http",children:"DELETE /api/external/v1/admins/users/{userSeq}\n"})}),"\n",(0,r.jsx)(n.admonition,{title:"Immediate and irreversible",type:"warning",children:(0,r.jsxs)(n.p,{children:["This is a hard delete. It bypasses the pending-delete grace peri
1od entirely and cannot be undone. There is no guard\npreventing you from deleting your own account or the tenant's only administrator. Use\n",(0,r.jsx)(n.a,{href:"#mark-an-account-for-deletion",children:"withdraw"})," unless you specifically intend an unrecoverable deletion."]})}),"\n",(0,r.jsx)(n.h2,{id:"accounts-pending-deletion",children:"Accounts pending deletion"}),"\n",(0,r.jsx)(n.p,{children:"Accounts marked for deletion wait for a scheduled date before being removed, and can be restored until then."}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-http",children:"GET /api/external/v1/admins/users/pending-delete\nPATCH /api/external/v1/admins/users/pending-delete/{userSeq}/restore\nPATCH /api/external/v1/admins/users/pending-delete/permanent-delete\n"})}),"\n",(0,r.jsx)(n.p,{children:"The listing accepts:"}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Parameter"}),(0,r.jsx)(n.th,{children:"Type"}),(0,r.jsx)(n.th,{children:"Required"}),(0,r.jsx)(n.th,{children:"Description"})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"ps"})}),(0,r.jsx)(n.td,{children:"integer"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsxs)(n.td,{children:["Page size, minimum ",(0,r.jsx)(n.code,{children:"1"})]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"pdSd"})}),(0,r.jsx)(n.td,{children:"date"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsxs)(n.td,{children:["Start of the range for when the account was marked; send with ",(0,r.jsx)(n.code,{children:"pdEd"})]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"pdEd"})}),(0,r.jsx)(n.td,{children:"date"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsxs)(n.td,{children:["End of the range for when the account was marked; send with ",(0,r.jsx)(n.code,{children:"pdSd"})]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"dsSd"})}),(0,r.jsx)(n.td,{children:"date"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsxs)(n.td,{children:["Start of the scheduled-deletion range; send with ",(0,r.jsx)(n.code,{children:"dsEd"})]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"dsEd"})}),(0,r.jsx)(n.td,{children:"date"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsxs)(n.td,{children:["End of the scheduled-deletion range; send with ",(0,r.jsx)(n.code,{children:"dsSd"})]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"ci"})}),(0,r.jsx)(n.td,{children:"long"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsxs)(n.td,{children:["Cursor - the last ",(0,r.jsx)(n.code,{children:"userSeq"}),"; send with ",(0,r.jsx)(n.code,{children:"cv"})]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"cv"})}),(0,r.jsx)(n.td,{children:"date"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsxs)(n.td,{children:["Cursor - the last ",(0,r.jsx)(n.code,{children:"pendingDeleteDate"}),"; send with ",(0,r.jsx)(n.code,{children:"ci"})]})]})]})]}),"\n",(0,r.jsxs)(n.p,{children:["Each entry reports ",(0,r.jsx)(n.code,{children:"pendingDeleteDate"}),", ",(0,r.jsx)(n.code,{children:"deleteScheduleTime"}),", and who marked the account. ",(0,r.jsx)(n.code,{children:"status"})," is always\n",(0,r.jsx)(n.code,{children:"PENDING_DELETE"}),"."]}),"\n",(0,r.jsxs)(n.p,{children:["Restoring returns the account to normal use. An account that is not in the pending-delete state returns\n",(0,r.jsx)(n.code,{children:"ADMIN_USER_001"}),"."]}),"\n",(0,r.jsxs)(n.p,{children:["Permanent deletion takes ",(0,r.jsx)(n.code,{children:"ul"}),", a non-empty array of ",(0,r.jsx)(n.code,{children:"userSeq"})," values, and removes them all. An empty list returns\n",(0,r.jsx)(n.code,{children:"REQUEST_001"}),". If any listed account is not actually pending deletion, the whole request fails with ",(0,r.jsx)(n.code,{children:"ADMIN_USER_002"}),"\nrather than partially applying - re-read the list and retry with only valid entries."]}),"\n",(0,r.jsx)(n.h2,{id:"license",children:"License"}),"\n",(0,r.jsx)(n.p,{children:"Three endpoints manage the Thinkfree Drive license."}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-http",children:"POST /api/external/v1/admins/register/license\nGET /api/external/v1/admins/get/license\nGET /api/external/v1/admins/get/license/status\n"})}),"\n",(0,r.jsx)(n.admonition,{title:"These three use a different response format",type:"caution",children:(0,r.jsxs)(n.p,{children:["The license endpoints do not use the common envelope. A successful registration returns HTTP 200 with
1no body, and the\ntwo read endpoints return the license fields at the top level. Failures return ",(0,r.jsx)(n.code,{children:'{"code": number, "error": "ENUM_NAME"}'}),"\nwhere ",(0,r.jsx)(n.code,{children:"error"})," is a constant name, not a message. Do not parse these responses with your common envelope handler."]})}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.code,{children:"GET /admins/get/license/status"})," is authorized for ",(0,r.jsx)(n.code,{children:"USER"})," rather than ",(0,r.jsx)(n.code,{children:"ADMIN"}),", so an ordinary account's key can read\nlicense status."]}),"\n",(0,r.jsx)(n.h3,{id:"register-a-license",children:"Register a license"}),"\n",(0,r.jsxs)(n.p,{children:["Send the license file as ",(0,r.jsx)(n.code,{children:"multipart/form-data"})," under ",(0,r.jsx)(n.code,{children:"licenseFile"}),". A malformed file returns HTTP 400 with the matching\ncode, a processing failure returns HTTP 500 with ",(0,r.jsx)(n.code,{children:"6999"}),", and a failure reading the upload returns HTTP 500 with ",(0,r.jsx)(n.code,{children:"4999"}),"."]}),"\n",(0,r.jsx)(n.h3,{id:"read-the-license",children:"Read the license"}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.code,{children:"GET /admins/get/license"})," returns the issued license."]}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Field"}),(0,r.jsx)(n.th,{children:"Type"}),(0,r.jsx)(n.th,{children:"Meaning"})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"publisher"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsxs)(n.td,{children:["Issuer; always ",(0,r.jsx)(n.code,{children:"TF"})]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"CATEGORY"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsxs)(n.td,{children:[(0,r.jsx)(n.code,{children:"TRIAL"})," or ",(0,r.jsx)(n.code,{children:"PRODUCTION"})]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LICENSE_TYPE"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsxs)(n.td,{children:[(0,r.jsx)(n.code,{children:"SITE"})," or ",(0,r.jsx)(n.code,{children:"PERSEAT"})]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LICENSE_ID"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"License identifier"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"CLIENT_NAME"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"Customer name"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"issuedOn"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"Issue date"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"expiresOn"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"Expiry date"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"updatedAt"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"When the license record was last refreshed"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"spents"})}),(0,r.jsx)(n.td,{children:"integer"}),(0,r.jsx)(n.td,{children:"Days elapsed since issue"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"days"})}),(0,r.jsx)(n.td,{children:"integer"}),(0,r.jsx)(n.td,{children:"Total validity in days"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"state"})}),(0,r.jsx)(n.td,{children:"boolean"}),(0,r.jsx)(n.td,{children:"Whether the license is currently valid"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"gracePeriod"})}),(0,r.jsx)(n.td,{children:"boolean"}),(0,r.jsxs)(n.td,{children:["Present and ",(0,r.jsx)(n.code,{children:"true"})," only while in the post-expiry grace period of up to eight days"]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"constrainValue"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsxs)(n.td,{children:["Seat limit; present only for ",(0,r.jsx)(n.code,{children:"PERSEAT"})]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"currentSeatNum"})}),(0,r.jsx)(n.td,{children:"integer"}),(0,r.jsxs)(n.td,{children:["Active accounts; present only for ",(0,r.jsx)(n.code,{children:"PERSEAT"})]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"availableSeatNum"})}),(0,r.jsx)(n.td,{children:"integer"}),(0,r.jsxs)(n.td,{children:["Remaining seats; present only for ",(0,r.jsx)(n.code,{children:"PERSEAT"})]})]})]})]}),"\n",(0,r.jsxs)(n.p,{children:["Read only the fields above. The response can carry additional internal values that are not part of this contract.\nA tenant with no license registered returns HTTP 404 with ",(0,r.jsx)(n.code,{children:"6998"}),"."]}
1),"\n",(0,r.jsx)(n.h3,{id:"read-license-status",children:"Read license status"}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.code,{children:"GET /admins/get/license/status"})," returns ",(0,r.jsx)(n.code,{children:"state"}),", ",(0,r.jsx)(n.code,{children:"days"}),", ",(0,r.jsx)(n.code,{children:"spents"}),", and ",(0,r.jsx)(n.code,{children:"expiresOn"}),". When the license needs\nattention it adds ",(0,r.jsx)(n.code,{children:"code"})," and ",(0,r.jsx)(n.code,{children:"resultMessage"})," to the same HTTP 200 response - a warning signal inside a successful\nresponse, not an HTTP error."]}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Condition"}),(0,r.jsx)(n.th,{children:(0,r.jsx)(n.code,{children:"code"})}),(0,r.jsx)(n.th,{children:(0,r.jsx)(n.code,{children:"resultMessage"})})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:"Expires within ten days"}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"6994"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LICENSE_UNDER_LIMIT"})})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:"Already expired"}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"6995"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LICENSE_FILE_EXPIRATION"})})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:"Seat limit exceeded, which takes precedence over both rows above"}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"6993"})}),(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"LICENSE_EXCEED_LIMIT"})})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:"Healthy"}),(0,r.jsx)(n.td,{children:"absent"}),(0,r.jsx)(n.td,{children:"absent"})]})]})]}),"\n",(0,r.jsxs)(n.p,{children:["When the seat limit is exceeded the response also carries ",(0,r.jsx)(n.code,{children:"currentSeatNum"}),", ",(0,r.jsx)(n.code,{children:"constrainValue"}),", and ",(0,r.jsx)(n.code,{children:"availableSeatNum"}),",\nwhich can be negative, and ",(0,r.jsx)(n.code,{children:"state"})," is forced to ",(0,r.jsx)(n.code,{children:"false"}),"."]}),"\n",(0,r.jsx)(n.h2,{id:"sign-in-settings",children:"Sign-in settings"}),"\n",(0,r.jsx)(n.p,{children:"Controls how users authenticate into the tenant."}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-http",children:"GET /api/external/v1/admins/login-settings\nPATCH /api/external/v1/admins/login-settings\n"})}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Parameter"}),(0,r.jsx)(n.th,{children:"Type"}),(0,r.jsx)(n.th,{children:"Required"}),(0,r.jsx)(n.th,{children:"Description"})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"loginType"})}),(0,r.jsx)(n.td,{children:"enum"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsxs)(n.td,{children:[(0,r.jsx)(n.code,{children:"local"}),", ",(0,r.jsx)(n.code,{children:"oidc"}),", or ",(0,r.jsx)(n.code,{children:"jwt"})]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"providers"})}),(0,r.jsx)(n.td,{children:"array"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsxs)(n.td,{children:["Identity providers; omit or send ",(0,r.jsx)(n.code,{children:"null"})," for ",(0,r.jsx)(n.code,{children:"local"})]})]})]})]}),"\n",(0,r.jsxs)(n.p,{children:["A ",(0,r.jsx)(n.code,{children:"jwt"})," configuration takes exactly one provider. An ",(0,r.jsx)(n.code,{children:"oidc"})," configuration may hold several but only one may be\n",(0,r.jsx)(n.code,{children:"ACTIVE"}),". Each provider carries ",(0,r.jsx)(n.code,{children:"ssoProviderSeq"})," when updating, ",(0,r.jsx)(n.code,{children:"displayName"}),", ",(0,r.jsx)(n.code,{children:"status"}),", and a ",(0,r.jsx)(n.code,{children:"config"})," object whose\n",(0,r.jsx)(n.code,{children:"type"})," must equal ",(0,r.jsx)(n.code,{children:"loginType"})," - a mismatch returns ",(0,r.jsx)(n.code,{children:"SSO_PROTOCOL_002"}),", and an unsupported protocol returns\n",(0,r.jsx)(n.code,{children:"SSO_PROTOCOL_001"}),"."]}),"\n",(0,r.jsxs)(n.p,{children:["An ",(0,r.jsx)(n.code,{children:"oidc"})," ",(0,r.jsx)(n.code,{children:"config"})," takes ",(0,r.jsx)(n.code,{children:"issuerUrl"}),", ",(0,r.jsx)(n.code,{children:"clientId"}),", and ",(0,r.jsx)(n.code,{children:"clientSecret"}),". A ",(0,r.jsx)(n.code,{children:"jwt"})," ",(0,r.jsx)(n.code,{children:"config"})," takes ",(0,r.jsx)(n.code,{children:"issuer"}),", an optional\n",(0,r.jsx)(n.code,{children:"audience"}),", and ",(0,r.jsx)(n.code,{children:"keySourceType"})," of ",(0,r.jsx)(n.code,{children:"public_key"})," or ",(0,r.jsx)(n.code,{children:"jwks"})," - supply ",(0,r.jsx)(n.code,{children:"publicKey"})," for the first and ",(0,r.jsx)(n.code,{children:"jwksUri"})," for the\nsecond. ",(0,r.jsx)(n.code,{children:"emailClaimName"})," names an alternative claim to read the email from, and ",(0,r.jsx)(n.code,{children:"errorRedirectUrl"})," is where a failed\nsign-in lands."]}),"\n",(0,r.jsxs)(n.p,{children:["The read response reports ",(0,r.jsx)(n.code,{children:"redirectUri"})," for the callback and ",(0,r.jsx)(n.code,{children:"superAdminEnforced"}),", which is ",(0,r.jsx)(n.code,{children:"true"})," when a super\nadministrator is imposing the setting across tenants."]}),"\n",(0,r.jsx)(n.admonition,{title:"The read endpoint returns secrets in clear text",type:"warning",children:(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.code,{children:"GET /admins/login-settings"})," includes ",(0,r.jsx)(n.code,{children:"clientSecret"})," and ",(0,r.jsx)(n.code,{children:"publicKey"})," as stored, unmasked. Treat the response as\nsensitive: do not log it, cache it in a browser, or pass it to a client application."]})}),"\n",(0,r.jsx)(n.h2,{id:"branding",children:"Branding"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-http",children:"GET /api/external/v1/admins/branding\nPUT /api/external/v1/admins/branding\n"})}),"\n",(0,r.jsxs)(n.p,{children:["Branding applies to the API Key's tenant; there is no identifier in the path. Send the update as\n",(0,r.jsx)(n.code,{children:"multipart/form-data"}),"."]}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Parameter"}),(0,r.jsx)(n.th,{children:"Type"}),(0,r.jsx)(n.th,{children:"Required"}),(0,r.jsx)(n.th,{children:"Description"})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"tabTitle"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsx)(n.td,{children:"Browser tab title, 2 to 30 characters"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"serviceName"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsx)(n.td,{children:"Service name, 2 to 30 characters"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"showPoweredBy"})}),(0,r.jsx)(n.td,{children:"boolean"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsx)(n.td,{children:"Whether to show the provider attribution"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"useDefault"})}),(0,r.jsx)(n.td,{children:"boolean"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsxs)(n.td,{children:[(0,r.jsx)(n.code,{children:"true"}
1)," to use the stock images, ",(0,r.jsx)(n.code,{children:"false"})," to supply all four"]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"favicon"})}),(0,r.jsx)(n.td,{children:"file"}),(0,r.jsx)(n.td,{children:"Conditional"}),(0,r.jsxs)(n.td,{children:["ICO or PNG, up to 500 KB; required when ",(0,r.jsx)(n.code,{children:"useDefault"})," is ",(0,r.jsx)(n.code,{children:"false"})]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"logoIcon"})}),(0,r.jsx)(n.td,{children:"file"}),(0,r.jsx)(n.td,{children:"Conditional"}),(0,r.jsxs)(n.td,{children:["PNG or SVG, up to 1 MB; required when ",(0,r.jsx)(n.code,{children:"useDefault"})," is ",(0,r.jsx)(n.code,{children:"false"})]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"logoImage"})}),(0,r.jsx)(n.td,{children:"file"}),(0,r.jsx)(n.td,{children:"Conditional"}),(0,r.jsxs)(n.td,{children:["PNG or SVG, up to 2 MB; required when ",(0,r.jsx)(n.code,{children:"useDefault"})," is ",(0,r.jsx)(n.code,{children:"false"})]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"emailLogo"})}),(0,r.jsx)(n.td,{children:"file"}),(0,r.jsx)(n.td,{children:"Conditional"}),(0,r.jsxs)(n.td,{children:["PNG or SVG, up to 2 MB; required when ",(0,r.jsx)(n.code,{children:"useDefault"})," is ",(0,r.jsx)(n.code,{children:"false"})]})]})]})]}),"\n",(0,r.jsxs)(n.p,{children:["When ",(0,r.jsx)(n.code,{children:"useDefault"})," is ",(0,r.jsx)(n.code,{children:"true"})," the four image fields are ignored without validation. When it is ",(0,r.jsx)(n.code,{children:"false"}
1)," all four are\nrequired; sending fewer returns ",(0,r.jsx)(n.code,{children:"REQUEST_001"}),"."]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-http",children:"GET /api/external/v1/admins/branding/images/{type}\n"})}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.code,{children:"type"})," is ",(0,r.jsx)(n.code,{children:"favicon"}),", ",(0,r.jsx)(n.code,{children:"logo-icon"}),", ",(0,r.jsx)(n.code,{children:"logo-image"}),", or ",(0,r.jsx)(n.code,{children:"email-logo"}),", and the required ",(0,r.jsx)(n.code,{children:"source"})," is ",(0,r.jsx)(n.code,{children:"custom"})," or ",(0,r.jsx)(n.code,{children:"default"}),"."]}),"\n",(0,r.jsxs)(n.p,{children:["A missing custom image returns ",(0,r.jsx)(n.code,{children:"BRANDING_001"}),"."]}),"\n",(0,r.jsx)(n.h2,{id:"access-restriction",children:"Access restriction"}),"\n",(0,r.jsx)(n.p,{children:"Limits where users may sign in from."}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-http",children:"PUT /api/external/v1/admins/access-restriction/countries\nPUT /api/external/v1/admins/access-restriction/ips\n"})}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Parameter"}),(0,r.jsx)(n.th,{children:"Type"}),(0,r.jsx)(n.th,{children:"Required"}),(0,r.jsx)(n.th,{children:"Description"})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"countries"})}),(0,r.jsx)(n.td,{children:"array"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsx)(n.td,{children:"Allowed ISO alpha-2 country codes"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"ips"})}),(0,r.jsx)(n.td,{children:"array"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsx)(n.td,{children:"Allowed IPv4 addresses or CIDR ranges"})]})]})]}),"\n",(0,r.jsxs)(n.p,{children:["CIDR host bits must be zero, and IPv6 is not supported. An invalid country code returns ",(0,r.jsx)(n.code,{children:"ACCESS_002"})," and an invalid\naddress returns ",(0,r.jsx)(n.code,{children:"ACCESS_004"}),"."]}),"\n",(0,r.jsx)(n.admonition,{title:"Both endpoints replace the whole list",type:"warning",children:(0,r.jsx)(n.p,{children:"Neither adds to what is already stored. Sending an empty array deletes every entry. Read the current list, modify it,\nand send the complete result."})}),"\n",(0,r.jsxs)(n.p,{children:["Turn the restriction on and off through\n",(0,r.jsx)(n.a,{href:"#system-configuration",children:(0,r.jsx)(n.code,{children:"system-config/access-restriction-status"})}),". Enabling it with no countries and no addresses\nregistered returns ",(0,r.jsx)(n.code,{children:"ACCESS_003"}),"."]}),"\n",(0,r.jsx)(n.h2,{id:"share-settings",children:"Share settings"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-http",children:"GET /api/external/v1/admins/share-settings\nPATCH /api/external/v1/admins/share-settings\n"})}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Parameter"}),(0,r.jsx)(n.th,{children:"Type"}),(0,r.jsx)(n.th,{children:"Required"}),(0,r.jsx)(n.th,{children:"Description"})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"se"})}),(0,r.jsx)(n.td,{children:"boolean"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsx)(n.td,{children:"Whether sharing is available at all"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"esa"})}),(0,r.jsx)(n.td,{children:"boolean"}),(0,r.jsx)(n.td,{children:"Conditional"}),(0,r.jsxs)(n.td,{children:["Allow sharing outside the organization; required when ",(0,r.jsx)(n.code,{children:"se"})," is ",(0,r.jsx)(n.code,{children:"true"})]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"sua"})}),(0,r.jsx)(n.td,{children:"boolean"}),(0,r.jsx)(n.td,{children:"Conditional"}),(0,r.jsxs)(n.td,{children:["Allow the ",(0,r.jsx)(n.code,{children:"SPECIFIC_USERS"})," share type; required when ",(0,r.jsx)(n.code,{children:"se"})," is ",(0,r.jsx)(n.code,{children:"true"})]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"ola"})}),(0,r.jsx)(n.td,{children:"boolean"}),(0,r.jsx)(n.td,{children:"Conditional"}),(0,r.jsxs)(n.td,{children:["Allow the ",(0,r.jsx)(n.code,{children:"ORG_LINK"})," share type; required when ",(0,r.jsx)(n.code,{children:"se"})," is ",(0,r.jsx)(n.code,{children:"true"})]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"pa"})}),(0,r.jsx)(n.td,{children:"boolean"}),(0,r.jsx)(n.td,{children:"Conditional"}),(0,r.jsxs)(n.td,{children:["Allow the ",(0,r.jsx)(n.code,{children:"PUBLIC_LINK"})," share type; required when ",(0,r.jsx)(n.code,{children:"se"})," is ",(0,r.jsx)(n.code,{children:"true"})]})]})]})]}),"\n",(0,r.jsxs)(n.p,{children:["When ",(0,r.jsx)(n.code,{children:"se"})," is ",(0,r.jsx)(n.code,{children:"true"}),", at least one of ",(0,r.jsx)(n.code,{children:"sua"}),", ",(0,r.jsx)(n.code,{children:"ola"}),", and ",(0,r.jsx)(n.code,{children:"pa"})," must also be ",(0,r.jsx)(n.code,{children:"true"}),". Enabling ",(0,r.jsx)(n.code,{children:"pa"})," requires ",(0,r.jsx)(n.code,{children:"esa"})," to be\n",(0,r.jsx)(n.code,{children:"true"})," as well."]}),"\n",(0,r.jsxs)(n.p,{children:["The read response adds ",(0,r.jsx)(n.code,{children:"isEnforced"}),". When it is ",(0,r.jsx)(n.code,{children:"true"}),", a super administrator is applying one setting to every tenant\nand the values returned are the global ones rather than this tenant's own."]}),"\n",(0,r.jsx)(n.h2,{id:"smtp",children:"SMTP"}),"\n",(0,r.jsxs)(n.p,{children:["One SMTP configuration exists per tenant. Sending ",(0,r.jsx)(n.code,{children:"smtpConfigSeq"})," updates the existing record; omitting it creates one."]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-http",children:"GET /api/external/v1/admins/smtp-config\nPOST /api/external/v1/admins/smtp-config\nPOST /api/external/v1/admins/smtp-config/test\n"})}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Parameter"}),(0,r.jsx)(n.th,{children:"Type"}),(0,r.jsx)(n.th,{children:"Required"}),(0,r.jsx)(n.th,{children:"Description"})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"clientName"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsx)(n.td,{children:"Customer name for the configuration"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"host"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsx)(n.td,{children:"SMTP server address"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"port"})}),(0,r.jsx)(n.td,{children:"integer"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsx)(n.td,{children:"SMTP port"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"encryptionType"})}),(0,r.jsx)(n.td,{children:"enum"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsxs)(n.td,{children:[(0,r.jsx)(n.code,{children:"SSL"}),", ",(0,r.jsx)(n.code,{children:"TLS"}),", or ",(0,r.jsx)(n.code,{children:"NONE"})]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"authType"})}),(0,r.jsx)(n.td,{children:"enum"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsxs)(n.td,{children:[(0,r.jsx)(n.code,{children:"IDPW"})," or ",(0,r.jsx)(n.code,{children:"OAUTH"})]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"username"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsx)(n.td,{children:"SMTP account"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"encPwd"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"Conditional"}),(0,r.jsxs)(n.td,{children:["Password; used when ",(0,r.jsx)(n.code,{children:"authType"})," is ",(0,r.jsx)(n.code,{children:"IDPW"})]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"oauthInfo"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"Conditional"}),(0,r.jsxs)(n.td,{children:["OAuth access token; used when ",(0,r.jsx)(n.code,{children:"authType"})," is ",(0,r.jsx)(n.code,{children:"OAUTH"})]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"fromAddress"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsx)(n.td,{children:"Sender address"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"testReceiverAddress"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"Yes"}),(0,r.jsx)(n.td,{children:"Where the test message is sent"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"smtpConfigSeq"})}),(0,r.jsx)(n.td,{children:"integer"}),(0,r.jsx)(n.td,{children:"Conditional"}),(0,r.jsx)(n.td,{children:"The configuration to update; required by the test endpoint"})]})]})]}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.code,{children:"encPwd"})," and ",(0,r.jsx)(n.code,{children:"oauthInfo"})," are not enforced by request validation even though one of them is needed in practice, so a\nconfiguration can be saved that cannot actually send. Use the test endpoint to confirm; a failed send returns\n",(0,r.jsx)(n.code,{children:"SMTP_CONFIG_002"}),", and reading a configuration that does not exist returns ",(0,r.jsx)(n.code,{children:"SMTP_CONFIG_001"}),"."]}),"\n",(0,r.jsx)(n.admonition,{title:"The read endpoint returns the SMTP password in clear text",type:"warning",children:(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.code,{children:"GET /admins/smtp-config"})," returns ",(0,r.jsx)(n.code,{children:"encPwd"})," decrypted. Treat the response as sensitive and keep it server-side."]})}),"\n",(0,r.jsx)(n.admonition,{title:"OAuth sending is not fully wired",type:"caution",children:(0,r.jsxs)(n.p,{children:["With ",(0,r.jsx)(n.code,{children:"authType"})," of ",(0,r.jsx)(n.code,{children:"OAUTH"}),", ",(0,r.jsx)(n.code,{children:"oauthInfo"})," is used directly as the access token and ",(0,r.jsx)(n.code,{children:"username"})," as the account. The server\ndoes not check that the token was issued for that account or for ",(0,r.jsx)(n.code,{children:"fromAddress"}),", and it does not refresh an expired\ntoken. Verify the pairing yourself and plan for manual token rotation."]})}),"\n",(0,r.jsx)(n.h2,{id:"system-configuration",children:"System configuration"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-http",children:"GET /api/external/v1/admins/system-config/general\nPUT /api/external/v1/admins/system-config/general\nGET /api/external/v1/admins/system-config/office\nPUT /api/external/v1/admins/system-config/office\nGET /api/external/v1/admins/system-config/storage\nGET /api/external/v1/admins/system-config/intellect\nPUT /api/external/v1/admins/system-config/intellect\nGET /api/external/v1/admins/system-config/mfa-status\nPUT /api/external/v1/admins/system-config/mfa-status\nGET /api/external/v1/admins/system-config/file-size-limit\nPUT /api/external/v1/admins/system-config/file-size-limit\nGET /api/external/v1/admins/system-config/access-restriction-status\nPUT /api/external/v1/admins/system-config/access-restriction-status\nGET /api/external/v1/admins/system-config/shares/exists\n"})}),"\n",(0,r.jsxs)(n.p,{children:["A ",(0,r.jsx)(n.code,{children:"PUT"})," that creates a setting for the first time returns ",(0,r.jsx)(n.code,{children:"201"}),"; updating an existing one returns ",(0,r.jsx)(n.code,{children:"200"}),"."]}),"\n",(0,r.jsx)(n.h3,{id:"general",children:"General"}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.code,{children:"clientDomain"})," is the tenant's client domain, returned as an empty string when unset."]}),"\n",(0,r.jsx)(n.admonition,{title:"Editing the domain is restricted in multi-tenant deployments",type:"note",children:(0,r.jsxs)(n.p,{children:["When more than one tenant is active, only a super administrator may change ",(0,r.jsx)(n.code,{children:"clientDomain"}),"; an ordinary administrator\nreceives ",(0,r.jsx)(n.code,{children:"SYSTEM_CONFIG_008"}),". When a base domain is registered, the value must end with it, otherwise the call fails\nwith ",(0,r.jsx)(n.code,{children:"BASE_DOMAIN_004"}),"."]})}),"\n",(0,r.jsx)(n.h3,{id:"office",children:"Office"}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.code,{children:"officeDomain"})," and ",(0,r.jsx)(n.code,{children:"officeAdapterName"}),", both required on update. ",(0,r.jsx)(n.code,{children:"officeDomain"})," is validated as a URL."]}),"\n",(0,r.jsx)(n.h3,{id:"storage",children:"Storage"}),"\n",(0,r.jsxs)(n.p,{children:["Read-only. Returns ",(0,r.jsx)(n.code,{children:"storageType"})," of ",(0,r.jsx)(n.code,{children:"CEPH"})," or ",(0,r.jsx)(n.code,{children:"S3"}
1),", plus ",(0,r.jsx)(n.code,{children:"bucketName"}),", ",(0,r.jsx)(n.code,{children:"region"}),", ",(0,r.jsx)(n.code,{children:"endPoint"}),", and ",(0,r.jsx)(n.code,{children:"status"}),"."]}),"\n",(0,r.jsx)(n.admonition,{title:"Storage credentials are returned unmasked",type:"warning",children:(0,r.jsxs)(n.p,{children:["The response includes ",(0,r.jsx)(n.code,{children:"accessKey"})," and ",(0,r.jsx)(n.code,{children:"secretKey"})," in clear text. Any administrator key that can call this endpoint can\nread the tenant's object-storage credentials. Restrict who can reach it and never forward the response to a client."]})}),"\n",(0,r.jsx)(n.h3,{id:"feature-toggles",children:"Feature toggles"}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.code,{children:"intellect"}),", ",(0,r.jsx)(n.code,{children:"mfa-status"}),", and ",(0,r.jsx)(n.code,{children:"access-restriction-status"})," each read and write a single ",(0,r.jsx)(n.code,{children:"enabled"})," boolean. There is no\n",(0,r.jsx)(n.code,{children:"intellectStatus"})," or ",(0,r.jsx)(n.code,{children:"status"})," field; use ",(0,r.jsx)(n.code,{children:"enabled"}),"."]}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.code,{children:"access-restriction-status"})," also returns ",(0,r.jsx)(n.code,{children:"allowedCountries"})," and ",(0,r.jsx)(n.code,{children:"allowedIps"}),". Setting ",(0,r.jsx)(n.code,{children:"enabled"})," to ",(0,r.jsx)(n.code,{children:"true"})," requires at\nleast one country or address to be registered already, otherwise it fails with ",(0,r.jsx)(n.code,{children:"ACCESS_003"}),"."]}),"\n",(0,r.jsx)(n.h3,{id:"file-size-limit",children:"File size limit"}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.code,{children:"maxFileUploadSize"})," is the upload ceiling in bytes. Send ",(0,r.jsx)(n.code,{children:"null"})," for no limit; any value you do send must be positive."]}),"\n",(0,r.jsx)(n.h3,{id:"share-data-check",children:"Share data check"}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.code,{children:"shares/exists"})," reports whether the tenant holds any share records, as a single ",(0,r.jsx)(n.code,{children:"exists"})," boolean. Use it before turning\nsharing off to find out whether doing so would affect existing shares."]}),"\n",(0,r.jsx)(n.h2,{id:"errors",children:"Errors"}),"\n",(0,r.jsxs)(n.p,{children:["See ",(0,r.jsx)(n.a,{href:"/docs/management/api/errors",children:"Errors"})," for the full list of codes these endpoints return."]})]})}function o(e={}){const{wrapper:n}={...(0,i.R)(),...e.components};return n?(0,r.jsx)(n,{...e,children:(0,r.jsx)(h,{...e})}):h(e)}},8453(e,n,s){s.d(n,{R:()=>t,x:()=>c});var d=s(6540);const r={},i=d.createContext(r);function t(e){const n=d.useContext(i);return d.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function c(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(r):e.components||r:t(e.components),d.createElement(i.Provider,{value:n},e.children)}}}]);
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.