For the complete documentation index, see llms.txt. This page is also available as Markdown.

Authenticating an existing Atsign

Learn how to do the initial onboard for an Atsign in your Dart application using AtAuth.authenticate

What is authentication?

Authentication is what you do every time an already-onboarded (activated) Atsign needs to connect to its atServer. Unlike onboarding, it does not generate new keys or touch the atServer's enrollment state, it reads the existing key material and proves ownership of the Atsign using PKAM.

This is the flow you write in almost every app, for almost every session. It never needs a CRAM key.

If the Atsign has never been activated, use Onboarding a new Atsign instead.

Prerequisites

  • An already-onboarded (activated) Atsign

  • Its .atKeys file

The core classes

Class
Description

AtAuth

Object that holds onboarding/authentication logic. Contains AtAuth.authenticate.

AtAuthRequest

Represents a request to authenticate an Atsign; passed to AtAuth.authenticate

AtAuthResponse

Represents a response after AtAuth.authenticate was executed

AtAuthSession

The auth→client hand-off object, populated on response.session on success

Authentication flows

There are several ways to parameterize AtAuth.authenticate, either by manipulating AtAuthRequest or by using different AtKeysIo implementations.

Flow
Summary

Simple Atsign authenticate, use all defaults

Read the .atKeys file from a non-default path

Use a custom atDirectory host:port

Read a .atKeys file saved behind a password

Implement retry and timeout functionality to AtAuth.authenticate

Listen for events during the AtAuth.authenticate process

Authenticate using AtKeys already held in memory, instead of a file. Good for ephemeral enrollments carried over from onboarding. Not recommended for beginners.

Validate the atServer is reachable and already activated before attempting authentication

The minimal flow

Copy and paste the code below. Be sure to replace the value of the variable atsign accordingly to the Atsign you already onboarded.

Custom keys path

Specify a different input directory using FileAtKeysIo.

Custom root domain

Specify a different atDirectory host:port.

Password-protected file

If the .atKeys file was saved with a passPhrase during onboarding, pass the same passPhrase to FileAtKeysIo to read it back.

Custom retry/timeout

Use retryOptions in AtAuthRequest to offer a good user experience for your users in your Dart application.

Progress listening

Listen for events using atAuth.progressStream.listen.

In-memory keys

This flow is not recommended for beginners. It is really only useful when key material already lives in memory. For example, right after onboarding in the same process, or when keys arrive over a channel you control rather than from disk.

InMemoryAtKeysIo keeps AtKeys in a process-local map instead of writing them to disk. The same instance can be reused across an onboard and a later authenticate in the same process:

InMemoryAtKeysIo.read throws AtKeysNotInMemoryException if nothing has been written for the Atsign yet, so the instance must be populated (by onboard(), or by calling atKeysIo.write(atsign, existingAtKeys) yourself) before it is used to authenticate.

This flow is not recommended because it is best to save keys in a hard disk to avoid catastrophic failures: losing cryptographic keys.

Checking the atServer status first

authenticate() already calls this internally, but calling it yourself lets you tell "this Atsign was never activated" apart from "the keys are wrong" before spending a PKAM round trip. This is useful for a clearer error message in a UI.

After authenticating

Check isSuccessful before touching session .

Now that we have authenticated, the next step is to obtain an AtClient instance in the next step.

Last updated