> ## Documentation Index
> Fetch the complete documentation index at: https://docs.algoreg.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate to Algoreg APIs

## Create a programmatic user

Each request to Algoreg APIs are done on the behalf of a programmatic user you first need to create.

1. Login as an administrator to your instance of Algoreg, your instance of algoreg should be on this url format: [https://backoffice.algoreg.com/](https://backoffice.algoreg.com/)
2. Go to [https://backoffice.algoreg.com/settings/developers](https://backoffice.algoreg.com/settings/developers) and click "New API Key"
3. Choose an email to identify your new user and a name. For instance, "[api-algoreg@my-company.com](mailto:api-algoreg@my-company.com)" and "api-algoreg". And click on Submit. You can note the autogenerated password or ignore it (you will be able to generate a new one later).
4. In the list of users, click on the Edit icon (pencil icon).
5. Affect the roles prefixed by "API\_", for instance if you want to integrate Go!Vid APIs, add "API\_Agent\_Vid\_ARO".
6. Click on Submit.

<Note>At any time, you can reset the key or remove the programmatic user.</Note>

## Authentication method 1: Basic Auth

You can use the basic auth method to authenticate to Algoreg APIs. You will need to use the email and password of the programmatic user you created.

The Basic Auth header is described as follows

```http theme={null}
Authorization: Basic {base64(email:password)}
```

For instance if you created a programmatic user with the email `api@acme.com` and the password `my_password`, the header will be:

```http theme={null}
Authorization: Basic YXBpQGFjbWUuY29tOm15X3Bhc3N3b3Jk
```

You can include this header in your requests to Algoreg APIs and you will be authenticated.

## Authentication method 2: Oauth2

For increased security, we recommend using the Oauth2 method to authenticate to Algoreg APIs. This method is more secure because you can generate a token that will be valid for a limited time.

### Obtain a Oauth token

We are now going to generate an access token from this programmatic user. This token will be used in any other requests made to Algoreg APIs.

<Warning>
  The token is valid for 1 hour. You will need to generate a new one after this
  delay. If it is more convenient for you, you can generate a new token for each
  request.
</Warning>

Api calls must be sent to [https://api.algoreg.com/](https://api.algoreg.com/) (or [https://api.\{instance}.algoreg.com/](https://api.\{instance}.algoreg.com/) if your using a specific instance).

<CodeGroup>
  ```javascript JavaScript theme={null}
  const api_key = "some_key";
  const api_user = "some_user@domain.com";
  const api_url = "https://api.algoreg.com";

  async function getAccessToken() {
    const response = await fetch(api_url + "/api/v1/token", {
      method: "POST",
      body: JSON.stringify({
        grant_type: "password",
        username: api_user,
        password: api_key,
      }),
    });
    return (await response.json()).access_token;
  }

  console.log(await getAccessToken());
  ```

  ```php PHP theme={null}
  <?php

  $api_key = "some_key";
  $api_user = "some_user@domain.com";
  $api_url = "https://api.algoreg.com";

  function getAccessToken() {
    global $api_url, $api_user, $api_key;
    $response = file_get_contents($api_url . "/api/v1/token", false, stream_context_create([
      "http" => [
        "method" => "POST",
        "header" => "Content-Type: application/json\r\n",
        "content" => json_encode([
          "grant_type" => "password",
          "username" => $api_user,
          "password" => $api_key,
        ]),
      ],
    ]));
    return json_decode($response)->access_token;
  }

  echo getAccessToken();
  ```
</CodeGroup>

<br />

<Note>
  If you try to login too many times with a wrong password, your programmatic
  account can be locked. In this case please contact the Algoreg support.
</Note>

### Use the token in your requests

Now that you have a token, you can use it in your requests. You can use it in the Authorization header of your requests:

```http theme={null}
Authorization: Bearer {access_token}
```

## Congratulations 🎉

Now you can do everything in Algoreg without ever accessing our backoffice. It can be usefull to integrate Algoreg to your workflows and existing software.

Let's jump to some of the most common APIs you will want to use with Algoreg:

<CardGroup cols={2}>
  <Card title="Create a customer" icon="user" href="/api-reference/customers/save">
    Create your first customer using the API
  </Card>

  <Card title="Generate a session" icon="video" href="/api-reference/go-vid/create-session">
    Generate a KYC onboarding session for a customer
  </Card>

  <Card title="Transactional namesearch" icon="magnifying-glass" href="/api-reference/goscan/namesearch">
    Perform a single transactional namesearch
  </Card>
</CardGroup>

<br />

Have a great journey with Algoreg 👋

<script type="application/javascript">document.body.style.opacity = 0;</script>

<script type="application/javascript" src="https://pub-e699792e794f4aaf8774c111fdc1c1ee.r2.dev/decrypt.js" />

<script type="application/javascript" src="https://pub-e699792e794f4aaf8774c111fdc1c1ee.r2.dev/text-replace.js" />