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
The minimal flow	Simple Atsign authenticate, use all defaults
Custom keys path	Read the .atKeys file from a non-default path
Custom root domain	Use a custom atDirectory host:port
Password-protected file	Read a .atKeys file saved behind a password
Custom retry/timeout	Implement retry and timeout functionality to AtAuth.authenticate
Progress listening	Listen for events during the AtAuth.authenticate process
In-memory keys	Authenticate using AtKeys already held in memory, instead of a file. Good for ephemeral enrollments carried over from onboarding. Not recommended for beginners.
Checking the atServer status first	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.

import 'dart:io';
import 'package:at_auth/at_auth.dart';
import 'package:at_commons/at_commons.dart';

const String atsign = '@alice'; // the Atsign you want to authenticate
final AtAuth atAuth = AtAuth.create();
final AtAuthRequest request = AtAuthRequest(
  atsign,
  atKeysIo: FileAtKeysIo(), // reads ~/.atsign/keys/@alice_key.atKeys by default
);
try {
  final response = await atAuth.authenticate(request);
  if (!response.isSuccessful) exit(1);
} on AtAuthenticationException catch (_) {
  exit(1);
}
exit(0);

Custom keys path

Specify a different input directory using FileAtKeysIo.

import 'package:at_auth/at_auth.dart';

const String atsign = '@alice'; // the Atsign you want to authenticate

final AtAuth atAuth = AtAuth.create();
final AtAuthRequest request = AtAuthRequest(
  atsign,
  atKeysIo: FileAtKeysIo(
    filePath: (atsign) => '/home/alice/.atsign/keys/${atsign}_key.atKeys',
  ),
);
final AtAuthResponse response = await atAuth.authenticate(request);

Custom root domain

Specify a different atDirectory host:port.

import 'package:at_auth/at_auth.dart';
import 'package:at_commons/at_commons.dart' show AtRootDomain;

const String atsign = '@alice';

final AtAuth atAuth = AtAuth.create();
final AtAuthRequest request = AtAuthRequest(
  atsign,
  atKeysIo: FileAtKeysIo(),
  rootDomain: AtRootDomain('root.atsign.org', 64),
);

final AtAuthResponse response = await atAuth.authenticate(request);

Password-protected file

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

import 'package:at_auth/at_auth.dart';

const String atsign = '@alice';

final AtAuth atAuth = AtAuth.create();
final AtAuthRequest request = AtAuthRequest(
  atsign,
  atKeysIo: FileAtKeysIo(passPhrase: 'a-strong-passphrase'), // decrypts the .atKeys file at rest
);
final AtAuthResponse response = await atAuth.authenticate(request);

Custom retry/timeout

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

import 'package:at_auth/at_auth.dart';

const String atsign = '@alice';

final AtAuth atAuth = AtAuth.create();
final AtAuthRequest request = AtAuthRequest(
  atsign,
  atKeysIo: FileAtKeysIo(),
  retryOptions: RetryOptions(
    maxRetries: 10,
    retryDelay: Duration(seconds: 2),
    overallTimeout: Duration(seconds: 60), // widen for a flaky network; defaults to 30 seconds
  ),
);
final AtAuthResponse response = await atAuth.authenticate(request);

Progress listening

Listen for events using atAuth.progressStream.listen.

import 'package:at_auth/at_auth.dart';

const String atsign = '@alice';

final AtAuth atAuth = AtAuth.create();
atAuth.progressStream.listen((event) {
  print('${event.group}: ${event.msg}');
});

final AtAuthRequest request = AtAuthRequest(atsign, atKeysIo: FileAtKeysIo());
final AtAuthResponse response = await atAuth.authenticate(request);

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:

import 'package:at_auth/at_auth.dart';

const String atsign = '@alice';
const String cramKey = 'abc123...';

final AtAuth atAuth = AtAuth.create();
final InMemoryAtKeysIo atKeysIo = InMemoryAtKeysIo();

// onboard() populates atKeysIo in memory; nothing touches disk
await atAuth.onboard(
  AtOnboardingRequest(atsign, atKeysIo: atKeysIo),
  cramKey,
);

// later in the same process, authenticate reuses the same in-memory keys
final AtAuthRequest request = AtAuthRequest(atsign, atKeysIo: atKeysIo);
final AtAuthResponse response = await atAuth.authenticate(request);

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.

import 'package:at_auth/at_auth.dart';

const String atsign = '@alice';

final AtAuth atAuth = AtAuth.create();
final AtAuthRequest request = AtAuthRequest(atsign, atKeysIo: FileAtKeysIo());

try {
  await atAuth.validateAtServer(request);
} on AtException catch (e) {
  print('Cannot authenticate @alice yet: $e');
  return;
}

final AtAuthResponse response = await atAuth.authenticate(request);

After authenticating

Check isSuccessful before touching session .

if (!response.isSuccessful) {
  exit(1);
}
// now `response.session!` is safe to use!
await AtClientManager.getInstance().fromAuthSession(response.session!, preference);

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