# 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](/dev-tools/affinidi-cli/manage-projects.md), 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](#create-a-key-pair).

Use [IAM](/dev-tools/affinidi-cli/manage-iam.md) (Policy) service of Affinidi to grant access and restrict the actions that PAT can perform on your projects.

```mermaid
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

```bash
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

```bash
affinidi  token create-token
```

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

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

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

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

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

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

### affinidi token delete-token

Deletes a Personal Access Token (PAT)

USAGE

```bash
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

```bash
affinidi  token delete-token -i [uuid]
```

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

### affinidi token get-token

Gets the details of a Personal Access Token (PAT)

USAGE

```bash
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

```bash
affinidi  token get-token -i [uuid]
```

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

### affinidi token list-tokens

Lists your Personal Access Tokens (PATs)

USAGE

```bash
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

```bash
affinidi  token list-tokens
```

### affinidi token update-token

Updates a Personal Access Token (PAT)

USAGE

```bash
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

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

```bash
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](https://aws.amazon.com/kms/), [GCP’s Cloud KMS](https://cloud.google.com/security-key-management) or [Azure Key Vault](https://azure.microsoft.com/products/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

```bash
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

```bash
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.

Important

Upon executing the command, the tool prompts you to provide a passphrase. It is recommended to set a passphrase for an additional layer of security. Remember your passphrase as it will be required later.

### 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

```bash
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

```bash
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](#affinidi-token-create-token) using Affinidi CLI.

## Personal Access Token Usage

You can use Personal Access Token (PAT) to generate [Authorisation Token](/dev-tools/affinidi-tdk.md#authorisation-token) and integrate with [Affinidi TDK](/dev-tools/affinidi-tdk) from your application.