> For the complete documentation index, see [llms.txt](https://developer.tapraise.com/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.tapraise.com/api/api-overview/authentication.md).

# Authentication

The API requires a Bearer authentication header. We recommend signing a short-lived JWT token on your client.

### What is a JWT token?

JSON Web Token (JWT) is an open standard ([RFC 7519](https://tools.ietf.org/html/rfc7519)) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with the **HMAC** algorithm) or a public/private key pair using **RSA** or **ECDSA**.

Although JWTs can be encrypted to also provide secrecy between parties, we will focus on *signed* tokens. Signed tokens can verify the *integrity* of the claims contained within it, while encrypted tokens *hide* those claims from other parties. When tokens are signed using public/private key pairs, the signature also certifies that only the party holding the private key is the one that signed it.

### How to create a token?

You can use any JWT-library that is capable to generate, sign and encode a token. You received the following credentials from TapRaise:

1. Account email address
2. Private key ID
3. Private key (PKCS8)

Please securely store the private key data, as it grants access to your data.

Use the header and claims as described below to create a JWT that is accepted by the API.

### Headers and Claims

**Header**

* `kid` (key id): What key was used for signature, use private key ID as provided.
* `alg` (algorithm): Algorithm used for signature, always `RS256`.

**Custom claims**

* `email` (email address): The account email address as provided.

**Reserved claims**

* `iss` (issuer): Issuer of the JWT, also the account email address as provided.
* `iat` (issued at time): Time at which the JWT was issued; can be used to determine age of the JWT.
* `exp` (expiration time): Time after which the JWT expires.

### Examples

{% tabs %}
{% tab title="Node with jose" %}

```javascript
const jose = require('jose');

// Provided by TapRaise
const algorithm = 'RS256';
const privateKey = '-----BEGIN PRIVATE KEY-----.....-----END PRIVATE KEY-----';
const privateKeyId = '03e718b3..........ab4583782';
const email = 'account-name@tapraise-xxxx.iam.gserviceaccount.com';

const customClaims = {
  email: email,
};

const header = {
  alg: algorithm,
  kid: privateKeyId,
};

const jwt = new jose.SignJWT(customClaims)
  .setProtectedHeader(header)
  .setIssuer(email)
  .setIssuedAt()
  .setExpirationTime('1h'); // Valid for 1 hour

(async () => {
  const importedKey = await jose.importPKCS8(privateKey, algorithm);
  const signed = await jwt.sign(importedKey);

  console.log(jwt); // token content
  console.log(signed); // signed token, used as Bearer token.
})();
```

{% endtab %}

{% tab title="Python with pyjwt" %}

```python
from datetime import datetime
import jwt

algorithm = "RS256"
private_key = "-----BEGIN PRIVATE KEY-----.....-----END PRIVATE KEY-----"
private_key_id = "03e718b3..........ab4583782"
client_email = "account-name@tapraise-xxxx.iam.gserviceaccount.com"

headers = {
    "alg": algorithm,
    "kid": private_key_id
}

payload = {
    "email": client_email,
    "iss": client_email,
    "iat": int(datetime.now().timestamp()),
    "exp": int(datetime.now().timestamp() + 3600)
}

encoded = jwt.encode(payload, private_key, algorithm, headers=headers)

print(encoded) # signed token, used as Bearer token
```

{% endtab %}

{% tab title="CLI" %}
**Creating a JWT with** [**jwt-cli**](https://github.com/mike-engel/jwt-cli)

{% code overflow="wrap" lineNumbers="true" %}

```bash
jwt encode --alg RS256 --kid replaceThisWithYourPrivateKeyId --iss account-name@tapraise-xxxx.iam.gserviceaccount.com --exp=1h --secret=@/path/to/private_key.pem '{"email": "account-name@tapraise-xxxx.iam.gserviceaccount.com"}'
```

{% endcode %}

**Decoding a JWT with jwt-cli**

```bash
jwt decode replaceThisWithYourJWT
```

{% endtab %}
{% endtabs %}

### Resources

* [jwt.io/introduction](https://jwt.io/introduction) - Introduction to JWT's
* [jwt.io/libraries](https://jwt.io/libraries) - Libraries
* <https://github.com/mike-engel/jwt-cli> - CLI tool to decode and encode JWTs
* [cloud.google.com/api-gateway/docs/authenticate-service-account](https://cloud.google.com/api-gateway/docs/authenticate-service-account#making_an_authenticated_request#making_an_authenticated_request) - Other examples