Identifiers & Credentials

11 min

what are you trying to do? embed an avatar in a website or app? jump to embedding credentials docid\ ybw n7hggzoepi cn86xm use the api to create, modify, or manage heads, head visuals, or other resources? jump to api credentials docid\ ybw n7hggzoepi cn86xm public vs private the key distinction the unith platform has two separate sets of identifiers and credentials they are not interchangeable public private used for embedding, client side integrations backend api calls, resource management safe to expose? yes, can appear in urls and client code no, keep in your backend only identifiers publicorgid , publicheadid orgid , headid , headvisualid credentials api key secret key , bearer token important api key ≠ secret key the api key is public and can be included in visible urls the secret key is private and must never be exposed they are completely different credentials internal ids (uuids) and public ids (slugs) can refer to the same resource, but they are not interchangeable using the wrong type will result in authentication or resolution errors api credentials use these when calling the unith api from your backend create, modify, or manage heads, head visuals, manage resources , etc authentication secret key your permanent credential used to generate bearer tokens never expose it outside your backend bearer token obtained from your secret key include it in every api request authorization bearer \<your bearer token> expires every 7 days — regenerate it using your secret key before it expires for more details on how to obtain and manage your secret key and bearer token, see the api user authentication guide docid\ a6pxi9wvcn3uxnytwj7ja identifiers name format what it identifies orgid uuid your organization headid uuid a specific head (avatar) headvisualid uuid the visual layer of a head you can retrieve all your identifiers with a single api call once you have a bearer token curl x get ' https //platform api unith ai/user/me https //platform api unith ai/user/me ' h 'accept application/json' h 'authorization bearer \\<your bearer token\>\ ' the response contains everything you need { "id" "xxxxxxxx xxxx xxxx xxxx xxxxxxxxxxxx", //your user id "firstname" "jane", "lastname" "doe", "email" "jane\@your company com", "organisation" { "id" "xxxxxxxx xxxx xxxx xxxx xxxxxxxxxxxx", //your org id (uuid) "publicid" "your company slug", //your public org id "apikey" "your public api key", } once you have your orgid, you can retrieve all your heads and their identifiers curl x get 'https //platform api unith ai/organisation/ \{orgid}\ /heads'\ h 'accept application/json' \ h 'authorization bearer \\<your bearer token\>\ ' the response returns an array of head objects \[ { "id" "xxxxxxxx xxxx xxxx xxxx xxxxxxxxxxxx", //head id (uuid) "orgid" "xxxxxxxx xxxx xxxx xxxx xxxxxxxxxxxx", "headvisualid" "xxxxxxxx xxxx xxxx xxxx xxxxxxxxxxxx", "name" "your head name", "publicid" "your head slug 12345", //public head id "orgpublicid" "your org slug", "publicurl" "https //stream unith ai/your org slug/your head slug 12345?api key=your public api key", "language" "en us", "isactive" true }] embedding credentials use these when embedding an avatar in a website, app, or any client side context the three values you need name what it is publicorgid your organization's human readable slug same across all your heads publicheadid the slug of the specific head you want to embed api key your public key for embedding same across all your heads where to find them inside unith interface all three values are in your avatar's streaming url to get it open the unith dashboard and find your avatar click view — the browser opens the streaming url read the values from the address bar https //stream unith ai/ \{publicorgid}\ / \{publicheadid}\ ?api key= \{apikey}\ embedding the avatar for a full guide on how to embed and integrate digital humans into your application, see the unith embed integration guide docid\ hemp8psh5xrdokwgsweaj