Manage Token

Manage your Personal Access Token (PAT) to connect and perform actions on Affinidi services on the user’s behalf.

Use a Token to generate a Personal Access Token (PAT) or a machine user to connect and perform operations to the Affinidi services on your behalf. Using PAT, you can automate specific tasks within your application and access multiple projects if granted by the user.

How does PAT authentication works

Personal Access Token (PAT) is like a machine user that acts on your behalf to the Affinidi services. You can use the PAT to authenticate to the Affinidi services and automate specific tasks within your application. A Personal Access Token (PAT) lives outside of Projects, meaning PAT can access multiple projects once granted by the user.

PATs use asymmetric keys where you are responsible of creating and maintaining the key pair. Please read about more about how to use Personal Access Tokens (PAT) and create the keys here.

Use IAM (Policy) service of Affinidi to grant access and restrict the actions that PAT can perform on your projects.

  flowchart TB
    subgraph Affinidi CLI
      user_token["1.1. Developer login to Affinidi"]
      create_project["1.2. Create a project"]
      project_access["1.3. Set an active project"]
      create_token["2.2. Create a token"]
      add_token_project["2.3. Add token to a project"]
      set_policies["2.4. Set policies for token"]

      user_token --> create_project
      create_project --> project_access
      user_token --> create_token
      create_token --> add_token_project
      project_access --> add_token_project
      add_token_project --> set_policies
    end

    subgraph Application
      direction TB
      sign_jwt["3.1. Sign JWT"]
      delegate_token["3.2. Create a delegate token"]
      call_project_api["3.3. Call Affinidi services"]

      sign_jwt --> delegate_token
      delegate_token --> call_project_api
    end

    create_keys["2.1. Create a key pair"]
    create_keys -. "publicKey PEM" .-> create_token
    create_keys -. "privateKey" .-> sign_jwt
    set_policies -. "granted access to" .-> call_project_api

Command References

    affinidi token

Use these commands for Personal Access Token (PAT) management

affinidi token create-token

Creates a Personal Access Token (PAT)

USAGE


affinidi  token create-token [--json] [--no-color] [--no-input] [-n [value]] [-k	 [value]] [-a RS256|RS512|ES256|ES512] [-w] [-p [value] [-g | -f [value]]]

FLAGS

-a, --algorithm=[option] [default: RS256] The specific cryptographic algorithm used with the key [options: RS256|RS512|ES256|ES512]

-f, --public-key-file=[value] Location of the public key PEM file

-g, --auto-generate-key Auto-generate private-public key pair

-k, --key-id=[value] Identifier of the key (kid)

-n, --name=[value] Name of the Personal Access Token, at least 8 chars long

-p, --passphrase=[value] Passphrase for generation of private public key pair

-w, --with-permissions Set token policies to perform any action on the active project

GLOBAL FLAGS

--json Format output as json.

--no-color Disables color in the output. If you have trouble distinguishing colors, consider using this flag.

--no-input Disables all the interactive prompts

EXAMPLES


affinidi  token create-token

affinidi token create-token --name "My new token"

affinidi token create-token -n MyNewToken --with-permissions

affinidi token create-token -n MyNewToken --auto-generate-key

affinidi token create-token -n MyNewToken --auto-generate-key --passphrase "MySecretPassphrase" --with-permissions

affinidi token create-token -n MyNewToken --public-key-file publicKey.pem --key-id MyKeyID --algorithm RS256 --with-permissions

affinidi token create-token -n MyNewToken -g -w

affinidi token delete-token

Deletes a Personal Access Token (PAT)

USAGE


affinidi  token delete-token [--json] [--no-color] [--no-input] [-i [value]]

FLAGS

-i, --token-id=[value] ID of the Personal Access Token

GLOBAL FLAGS

--json Format output as json.

--no-color Disables color in the output. If you have trouble distinguishing colors, consider using this flag.

--no-input Disables all the interactive prompts

EXAMPLES


affinidi  token delete-token -i [uuid]

affinidi token delete-token --token-id [uuid]

affinidi token get-token

Gets the details of a Personal Access Token (PAT)

USAGE


affinidi  token get-token [--json] [--no-color] [--no-input] [-i [value]]

FLAGS

-i, --token-id=[value] ID of the Personal Access Token

GLOBAL FLAGS

--json Format output as json.

--no-color Disables color in the output. If you have trouble distinguishing colors, consider using this flag.

--no-input Disables all the interactive prompts

EXAMPLES


affinidi  token get-token -i [uuid]

affinidi token get-token --token-id [uuid]

affinidi token list-tokens

Lists your Personal Access Tokens (PATs)

USAGE


affinidi  token list-tokens [--json] [--no-color] [--no-input]

GLOBAL FLAGS

--json Format output as json.

--no-color Disables color in the output. If you have trouble distinguishing colors, consider using this flag.

--no-input Disables all the interactive prompts

EXAMPLES


affinidi  token list-tokens

affinidi token update-token

Updates a Personal Access Token (PAT)

USAGE


affinidi  token update-token [--json] [--no-color] [--no-input] [-i [value]] [-n	 [value]] [-k [value]] [-f [value]] [--algorithm RS256|RS512|ES256|ES512]

FLAGS

-f, --public-key-file=[value] Location of the public key PEM file

-i, --token-id=[value] ID of the Personal Access Token

-k, --key-id=[value] Identifier of the key (kid)

-n, --name=[value] Name of the Personal Access Token, at least 8 chars long

--algorithm=[option] [default: RS256] The specific cryptographic algorithm used with the key [options: RS256|RS512|ES256|ES512]

GLOBAL FLAGS

--json Format output as json.

--no-color Disables color in the output. If you have trouble distinguishing colors, consider using this flag.

--no-input Disables all the interactive prompts

EXAMPLES


affinidi  token update-token -i [uuid] -n MyNewToken -k MyKeyID -f publicKey.pem

affinidi token update-token --token-id [uuid] --name "My new token" --key-id "My key ID" --public-key-file publicKey.pem --algorithm RS256

Setting up your PAT keys

To create and use your Personal Access Token you will require a key-pair. You can either create it yourself or rely on a cloud provider to securely manage your keys, such as AWS KMS, GCP’s Cloud KMS or Azure Key Vault

Create a Key-Pair

To create a key-pair, open your command prompt (Windows) / command line (Linux/Mac OS) and run the command below using either of the following tools:

Using ssh-keygen
ssh-keygen -b 4096 -t rsa -f key-pair

The -t rsa indicates that the key algorithm to use is rsa when creating your key-pair. You can used any of the following key algorithms depending on your requirement: [dsa | ecdsa | ecdsa-sk | ed25519 | ed25519-sk | rsa].

The -b 4096 indicates the key-size of your key-pair (optional).

The -f key-pair indicates the filename of the keys to be created (You may change the key-pair filename).

Using openssl
openssl genpkey -algorithm RSA -out private-key.pem -aes-128-cbc -pass pass:hello

The -algorithm RSA indicates the key algorithm to be RSA.

The -out private-key.pem indicates the output filename of the private key.

The -aes-128-cbc indicates the key will be encrypted with 128 bit AES.

The -pass pass:hello sets hello as the passphrase.

Create a Public Key in PEM Format

After creating your key-pair, you must create the public key in Privacy Enhanced Mail (PEM) format. To do this, run the command below using either of the following tools:

Using ssh-keygen
ssh-keygen -f key-pair.pub -e -m pem > public-key.pem

The -f key-pair.pub is the filename of your public key generated in the previous command which is used to generate the the PEM key file.

The -m pem indicates the key format output to PEM.

Using openssl
openssl rsa -in private-key.pem -pubout -out public-key.pem

The -in private-key.pem indicates the source private-key file where the public key is derived.

The -out public-key.pem indicates the output filename of the public key that is created.

The public-key.pem is the public key file in PEM format, which you use as the input to create the token using Affinidi CLI.

Personal Access Token Usage

You can use Personal Access Token (PAT) to generate Authorisation Token and integrate with Affinidi TDK from your application.