Skip to main content

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/callback for 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.
Keep the secret where only your server can read it. Never put it in browser code, in a mobile app, or in a repository. If it leaks or you lose it, make a new one on the app page. The old one stops at once.
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.
A later change to the name, the logo, a return address, or a permission goes to a reviewer first. Your app keeps working as it is until the change is approved. A change of a color, and a removal of an address or a permission, are live at once.
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 state in the address is the one that you kept. Then exchange the code.
Keep the tokens in your own session, for example a sealed cookie that scripts cannot read.
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.
The demo uses this flow. Its source is a small example of each step.

Browser flow

For an app with no backend. The tokens are in the browser, so use this only where that is acceptable.
The client keeps the session in 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.
Or with @urantia/api:
A 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. Pass since to the list, and keep the syncedAt of the answer for the next sync.
  • GET /me/bookmarks?since= and GET /me/notes?since= take an ISO 8601 time.
  • syncedAt is a little before the time of the read, so an item can come two times. Keep one item for each id.
  • 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 since older than 90 days, or older than the oldest kept delete when the 1,000 are full, gets a 410: get the full list again, without since.
  • 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 the updatedAt 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} requires updatedAt (since November 9, 2026). Without it, the answer is a 400.
  • If the note changed, the answer is a 409 with the note as it is now in current. @urantia/api 0.12.0 throws NoteConflictError, with that note in err.current.
  • Two saves of a bookmark of the same paragraph make one bookmark. The first save answers 201, and a later save answers 200.

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 a 401. 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 /me routes take a paragraph as 2:0.1, 2.0.1, or 1: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 no state, 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.