openpreference
GitHub Sign in

Register a client

A client is an app or service that reads preferences from this server. Registering one gives you a client ID and a secret, and it tells the people whose preferences you read who you are and why you are asking.

What you can read without a client

Anything a person has set to Everyone is on their public card and at /opi/preferences/their-handle. No registration, no token. The Developer quickstart shows the three requests.

What a client adds

  • Approved apps. With a client, you can send a person through /oauth/authorize and ask for specific preference types. They see your name and purpose and approve or decline. Approved preferences come back to your redirect URI with a token.
  • Trusted apps. Once your client is listed on the trust registry, it can request preferences people have set to Trusted apps with the client_credentials grant, server to server, with no per-person step.

What registering asks for

  • Client name. Shown to people in their access log and on the consent screen.
  • Purpose statement. One short paragraph on what you do with the preferences. It is required, it applies to every request the client makes, and people read it before approving.
  • Homepage. Optional. Linked from the consent screen.
  • Redirect URIs. Needed only if you will ask people for consent. One per line, HTTPS.

Steps

  1. Create an account at /signup if you do not have one. The account that registers a client owns it.
  2. Sign in and open Developer at /developer.
  3. Choose New client (/developer/clients/new) and fill in the fields above.
  4. Copy the client ID and secret from the page that follows. The secret is shown once. If you lose it, rotate it from the client's page; the old secret stops working at once.

Getting on the trust registry

The seed registry is curated by hand. When your client is working against Approved apps and you want Trusted apps access, write to hello@openpreference.org with your client ID, homepage and purpose statement. Listed clients appear on the trust registry with the categories they were verified for.

Next