Extensions and tokens
An extension is an extra request that travels with an operation, such as sign-in. You add it to the operation's first call, and you read its answer from the result after verification.
API reference:JavaScript
Callback method: how the response comes back
By default, the authenticator delivers the response as a form POST to your callback URL. A client-side application can ask for a GET with the response in the query string, or for the response in the URL fragment, which never reaches a server.
| Method | Delivery |
|---|---|
POST | A form POST to your callback URL with a response field. The default. |
GET | A GET with response in the query string. For client-side applications. |
HASH | A GET with response in the URL fragment. The fragment never reaches a server. |
Ask for it with ext: {callbackMethod: 'GET'} or ext: {callbackMethod: 'HASH'}. Nothing comes back in the result. The response arrives the way you asked.
Private profile: ask for the details the user keeps on the device
The private profile holds the initials, the name, and the email address that the user entered in the authenticator. It is stored on the device and never published. When you request it, the authenticator shows a switch on the approval screen, and the user decides. The choice is remembered for your website. If the user agrees, the fields arrive in the result.
| Ask for at sign-in | Get back in the result |
|---|---|
ext: {privateProfile: true} | ext.privateProfile with initials, name, and email, when the user agreed. Absent otherwise. |
Manifest: your name and icon on the user's home screen
The authenticator lists the websites a user signed in to on its home screen. With the manifest, you can set your website's name, the page to open, and an icon. Set it with ext: {manifest: {name, startUrl, iconUrl}}. Nothing comes back in the result.
| Field | Meaning |
|---|---|
name | The name shown to the user, at most 255 bytes. |
startUrl | The page that opens from the home screen. It must be on the same origin as your callback URL. Otherwise, the base URL of the callback opens instead. |
iconUrl | A PNG or JPEG file of up to 128 KB, served with permissive CORS headers. |
Tokens: permission for later requests
Sign-in is the only operation that starts on its own. Ping, sign, stamp, and attest need a token that you obtained at sign-in. A token is the user's standing permission for one kind of request from your website. The device keeps it, and you receive a copy in the sign-in result. Request each token you plan to use. The approval screen tells the user what each one allows, and approving the sign-in grants them.
| Ask for at sign-in | Get back in the result | Use it for |
|---|---|---|
ext: {pingToken: true} | ext.pingToken | Ping, a silent check that the user still holds the keys |
ext: {signToken: true} | ext.signToken | Sign, a signature over a document or a message |
ext: {stampToken: true} | ext.stampToken | Stamp, a silent proof of the session for another website |
ext: {attestToken: true} | ext.attestToken | Attest, attestations from providers you trust |
Store the tokens with the user's session, and pass the right one as token when you start the later operation. Two rules apply. The later operation's callback URL must share its base with the sign-in callback URL, its origin and path up to the last slash, because the token is bound to that base and to the device that issued it. And every sign-in issues new tokens and drops the old ones, so replace what you stored whenever the user signs in again.
Before you rely on an extension
- The user can decline an extension, and an authenticator may not support it. Read the result and handle a missing answer.
- The private profile is text the user typed. Escape it before you render it, and store only what you need.
- Tokens expire with the next sign-in. Replace the stored token whenever the user signs in again.