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

atKeys

The file that contains the set of cryptographic keys belonging to an Atsign.

What is the atKeys file?

The atKeys file is a set of cryptographic keys that provides devices the ability to authenticate into their AtServer and encrypt data for other Atsigns.

This is a file. Not to be confused with "AtKeys" which are the identifiers used in atRecords.

File Conventions

The name of the file will always follow this format:

<@atsign>_key.atKeys

Example: @alice_key.atKeys

The location of your atKeys files will almost always be automatically generated to this directory on your computer (MacOS, Linux, Windows).

$HOME/.atsign/keys/

If on a mobile device, you will be manually saving it to a safe location via your mobile device's file system. You will need to manually keep track of this key's location, so be sure to keep it somewhere safe!

What is activation?

Activating is the one-time, irreversable bootstrapping of a freshly provisioned Atsign. During activation, the client generates a cryptographic identity (a keypair) and registers it with the server as the proof of ownership.

The end result of activation is the .atKeys file; a portable credential file that represents your ownership of that Atsign. Ensure that you backup this file, as losing it means your Atsign's data becomes unrecoverable!

Activating is also known as "CRAM authentication" or "onboarding."

Activating can be done with the at_activate binary which can be downloaded several ways: from pub.dev, NoPorts release archives, or from GitHub source.

at_activate

Installing at_activate

at_activate is Atsign's official activation CLI tool. It contains functions like initial activation (CRAM) and for generating additional namespace-scoped copies (APKAM).

To install it, you must have Dart installed on your system.

  1. Ensure you have Dart installed

  1. Install at_activate using dart pub

  1. You should be able to run at_activate in your terminal

If missing, check $HOME/.pub-cache/bin for the at_activate binary.

Uninstalling at_activate

Simply use dart pub global deactivate

Initial activation

Ensure you have at_activate installed before moving on. Check out Installing at_activate on how to do that.

  1. Use the onboard command to onboard your Atsign. Replace <@atsign> with your Atsign. Example: at_activate onboard -a @alice

  1. You will then be prompted with a yes/no question. It is very important you backup and keep this file safe, once it is generated in the next steps. Enter "Y" and continue.

  1. You will receive an OTP in your email. Enter the OTP into the terminal.

  1. Your Atsign will then be activated and manager keys will be generated in $HOME/.atsign/keys

  1. Backup a copy of this file in some place safe (like a personal drive or a secure cloud storage).

Enrolling new devices

This is also known as creating an "APKAM copy" of your keys.

Now that your Atsign is activated, we can administer a new copy of the .atKeys file with a namespace-restriction.

A namespace-restriction means that this new .atKeys file copy will only have read and/or write access to certain namespaces. Read more on namespaces here.

The following steps are typically done on two separate devices, but is still possible to do on one. We will refer to Device 1 as the device with the manager set of keys and Device 2 as the device who wishes to enroll under this Atsign.

Device
Purpose

Device 1

The device with the manager .atKeys file

Device 2

The enrolling device that will generate the new .atKeys file copy

Before beginning, you must establish a few strings and keep this in mind.

Variable
Purpose
Example

App Name

App namespace that this key will belong to

my_app

Device Name

The name of the enrolling device

linux_server_1

Device 1 will generate an OTP and create an auto approval process, then Device 2 will send the enrollment request and this will automatically generate an APKAM .atKeys file copy.

  1. On Device 1, generate an OTP. Take note of this OTP, as it will be needed in step 3.

Replace <@atsign> with the Atsign you are making a copy of.

Tip: you can make this OTP useable for longer by setting an expiry by appending --expiry 2h to the command above.

  1. On Device 1, create an auto approval service.

Parameter
Description
Example

<@atsign>

The Atsign you are making a copy of

@alice

<app_name>

Name of the application/use case. Think of this as the purpose you are making this key for.

noports

<device_name>

Device name that uniquely identifies this enrollment from other enrollments.

linux_server_01

This will set up an auto service with a limit of 1. Leave this process running in the background.

  1. On Device 2, send the enrollment request.

Parameter
Description
Example

<@atsign>

Atsign you are making a copy of

@alice

<app_name>

The same app name from Step 2

noports

<device_name>

The same device name from Step 1

linux_server_01

<[namespace:r?w?]>

A list of comma-separated namespace and their read/write permissions. If you want this copy to simply be a revokable copy with all access, set this to *:rw

"*:rw"

"sshnp:rw,sshrvd:rw,noports:r,at_talk:w"

<OTP>

The one-time passcode from Step 1

ABC123

Change all parameters. Note that you have to replace <@atsign> twice in this command (-a and --keys ).

If you have set up an auto approval service up correctly (which is running in the background from Step 2), then executing this enroll command should exit successfully after a couple of seconds.

Example command & output:

Exceptions

AT0032 - Exception

This is a common exception that many people run into.

Your error message will say that this enrollment is in an approved state or a pending state.

To fix the pending error, go to Pending State.

To fix the approved error, go to Approved State.

Pending State

You most likely cancelled the enrollment process or missed a step during your Enrolling new device handshake.

To fix this, go to Device 1 (the device with the manager .atKeys file) and we will have to deny and delete this enrollment request. If your enrollment error says it's in a pending state, then you will need to run these two operations: deny and delete.

  1. Go to Device 1 (the device with the manager .atKeys file).

  2. Confirm your error message is similar to below (says "in pending state ")

  1. Run the list command and copy the enrollment ID of the faulty enrollment request.

Example:

It is very important we leave the firstDevice enrollment untouched.

In this scenario, I will copy the enrollment ID 460d24b9-9194-4718-bef2-96f7f467b04b .

  1. Run the deny command.

Example:

  1. Run the delete command.

Example:

  1. Follow steps 1-3 again in Enrolling new devices and that should resolve the error from coming up again!

Approved State

You are most likely trying to re-enroll an Atsign that has been previously enrolled on another device, and you would like to now re-enroll on a new completely separate device.

To fix this, go to Device 1 (the device with the manager .atKeys file) and we will need to revoke and delete.

  1. Go to Device 1 (the device with the manager .atKeys file)

  2. Confirm that error message you got on Device 2 is similar to below (it says "in approved state")

  1. Run the list command and copy the enrollment ID of the faulty enrollment request.

Example:

It is very important we leave the firstDevice enrollment untouched.

In this scenario, I will copy the enrollment ID 7dec3458-a939-4296-82ea-a6e042e72f52.

  1. Run the revoke command.

Example:

  1. Run the delete command.

Example:

  1. Follow steps 1-3 again in Enrolling new devices and that should resolve the error from coming up again!

Help! I've lost my .atKeys

Atsign cannot recover your lost cryptographic keys.

The only path forward is to reset your atServer which will result in all data being wiped. However, your Atsign (handle) will still be usable.

To reset your Atsign, go to https://my.atsign.com, login with the email address that is tied to that Atsign, then navigate to the manage page of your Atsign and open the Reset dropdown. Type the Atsign to proceed with resetting your atServer.

You can also reach out to support@atsign.com and we can help you reset your Atsign. Please reach out with the corresponding email that is tied to the relevant Atsign.

Last updated