# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.tapraise.com/api/api-overview/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.