Install
Overview
@urantia/auth signs people in through accounts.urantiahub.com. A person signs in once with a 6-digit email code or with Google, sees what your app asks for, and allows it. Your app then gets tokens for the parts of the API that the person allowed.
The package has two entries:
The content API itself needs no key and no account. You only need this package for a person’s own data: bookmarks, notes, reading progress, and reader settings.
Register your app
1
Open the developer pages
Go to accounts.urantiahub.com/apps and sign in with your UrantiaHub account.
2
Register an app
Press Register an app and fill in:
- Name: people see it on the sign-in page.
- App ID: small letters, numbers, and hyphens. It can never change, because your code uses it.
- What does the app do?: two or three sentences for the reviewer.
- Return address: where people land after they sign in (also called a redirect URI). Use
http://localhost:3000/callbackfor local work. - What the app can do: the permissions that your app needs. Ask only for what you use.
3
Save the secret
You see the App ID and the App secret. The secret is shown one time.
4
Build while it is in review
A new app works for you at once, so you can build and test. Other people can sign in after a reviewer approves it, which takes a few days at most. You get an email with the decision.
Server flow (recommended)
1
Start the sign-in
Make the address of the sign-in page. Keep
state and codeVerifier in a short-lived cookie that scripts cannot read, and send the person to url.2
Finish on your return address
Check that the Keep the tokens in your own session, for example a sealed cookie that scripts cannot read.
state in the address is the one that you kept. Then exchange the code.3
Refresh before the access token ends
An access token lasts 15 minutes. A refresh token lasts 90 days from its last use, and each one works one time: a refresh gives you a new pair.
4
Sign out
End the sign-in on the service and clear your own session. The person stays on your page.After a sign-out, pass
askAccount: true to the next createAuthorizeUrl. The accounts site then shows its sign-in page, and does not sign the person in by itself.Browser flow
For an app with no backend. The tokens are in the browser, so use this only where that is acceptable.localStorage, refreshes the access token by itself, and follows a sign-out in another tab.
Use the token
Send the access token as a bearer token.@urantia/api:
401 means that the token ended, or that the person removed your app in their account. Try one refresh. If the refresh is refused, clear your session.
Sync bookmarks and notes
If your app keeps a copy of a person’s bookmarks or notes, ask only for what changed. Passsince to the list, and keep the syncedAt of the answer for the next sync.
GET /me/bookmarks?since=andGET /me/notes?since=take an ISO 8601 time.syncedAtis a little before the time of the read, so an item can come two times. Keep one item for eachid.- The service keeps a delete for 90 days, and at most the newest 1,000 deletes of bookmarks, and of notes, for each person. A
sinceolder than 90 days, or older than the oldest kept delete when the 1,000 are full, gets a410: get the full list again, withoutsince. - There are no webhooks. Sync when your app opens or when the person asks.
Change a note that another app can change
A person can change the same note in two apps. Send theupdatedAt of the note as your app read it. If the note changed after that, the API refuses the change, so your app does not write over the other change.
PUT /me/notes/{id}requiresupdatedAt(since November 9, 2026). Without it, the answer is a400.- If the note changed, the answer is a
409with the note as it is now incurrent.@urantia/api0.12.0 throwsNoteConflictError, with that note inerr.current. - Two saves of a bookmark of the same paragraph make one bookmark. The first save answers
201, and a later save answers200.
Permissions
A read-only permission allows
GET only. A full permission includes its read-only one, so a person who allowed bookmarks is not asked again for bookmarks:read. Start with read-only permissions if your app only reads.
A token reaches only what its permissions allow. Your app can ask only for permissions that it registered. A new permission later asks the person again.
What a person can do
A person manages their account at accounts.urantiahub.com. There they see each app that has access, remove one, download a copy of their data as one file, or delete the account. A removal holds at once: your next request with that person’s token gets a401. A good place for a link to that page is next to your sign-out button.
Data, security, and terms
- Where the data is: account data is in a Postgres database at Supabase, in the United States, encrypted at rest. All traffic uses TLS.
- How it is kept: row level security is on for every table. App secrets and refresh tokens are stored only as hashes. The service never stores a raw IP address.
- A breach: if a breach touches the data of people who signed in through your app, we tell you and them without delay.
- If the service ends or changes hands: people get the chance to download or delete their data first.
- Age: the service is not for children. It is not directed at anyone under 18.
- Terms and privacy: the Terms of Service and the Privacy Policy of urantia.dev cover the API and this SDK.
- License: the content of the API is CC0 and the code is MIT. You can use all of it, in research and in published work. Credit is not required, and a link to urantia.dev is welcome.
- References: the
/meroutes take a paragraph as2:0.1,2.0.1, or1:2.0.1, and store the global ID (1:2.0.1). - Reading progress: each app decides when a paragraph counts as read. The service stores what an app sends.
- Stability: a change that breaks a route comes as a new route, never as a change of the old one. Changes are in the changelog.
- Rate limit: 200 requests a minute for each caller address.
- Review and testing: other people can use your app after a review. Until then, you, the owner, can sign in to it.
Check a token in your own backend
If your backend receives an access token from your own client, verify it before you trust it.Options of the browser client
Security notes
- PKCE and state: each sign-in uses a new PKCE verifier and a new
state. A return with nostate, or with another one, is refused. - Short tokens: an access token lasts 15 minutes. A refresh token works one time. If an old one comes back, the service ends that sign-in.
- The secret stays on your server: the server flow never sends it to a browser.
- Review: each app is reviewed before other people can use it, and each later change to what people see or to what the app can reach.

