# Authentication

## Anonymous user

Anonymous/unidentified users can use ApiRTC library through your apiKey only.

{% hint style="info" %}
Be mindful that your apiKey is readable by any user. 
{% endhint %}

<pre class="language-javascript"><code class="lang-javascript"><strong>// Declare a new anonymous UserAgent
</strong><strong>// - be mindful of the uri starting by 'apiKey:"
</strong><strong>var ua = new apiRTC.UserAgent({uri: 'apiKey:#HERE_YOUR_APIKEY#' });
</strong>ua.register({cloudUrl: 'https://cloud.apirtc.com'})
     .then( session => {...});
</code></pre>

## Authentication via login/password

ApiRTC library and REST APIs supports login/password authentication.

However, for any frontend implementation, we recommend to use a JWT to avoid leaking your identifiers publicly.

<pre class="language-javascript"><code class="lang-javascript">// Declare a UserAgent pointing to an existing ApiRTC user account
// - be mindful of the uri starting by 'apirtc:"
<strong>var ua = new apiRTC.UserAgent({uri: 'apirtc:#your.login.apirtc@email.com#' });
</strong>
//Pass your password when registering
ua.register({cloudUrl: 'https://cloud.apirtc.com', password: '#YOUR_PASSWORD_HERE#'})
    .then( session => {...});
</code></pre>

## Authenticate with a JWT token

ApiRTC library is accepting JWT authentication, whether the token is emitted:

* by the ApiRTC platform through the authentication endpoint,&#x20;
* or by any external authentication server that respect the [JWT standard](https://en.wikipedia.org/wiki/JSON_Web_Token).

```javascript
// Declare a new anonymous-like UserAgent
// - be mindful of the uri starting by 'apiKey:"
var ua = new apiRTC.UserAgent({uri: 'apiKey:#HERE_YOUR_APIKEY#' });

//When registering, 
ua.register(
    {cloudUrl: 'https://cloud.apirtc.com', 
    id: '#USER_ID#',
    token: "#JWT_STRING_HERE#"})
    .then( session => {...});
```

## More about the JWT authentication

The authentication call-flow is illustrated below:

{% @mermaid/diagram content="sequenceDiagram
ApiRTC platform-->Authentication server: Shared `secret` and `apikey`
Web Application->>Authentication server: Request a JWT corresponding to a `userId`
Authentication server->>Web Application:Return a JWT containing a shared `secret`
Web Application->>ApiRTC platform:Register a UserAgent with JWT (crypted), apikey and userId
ApiRTC platform->>ApiRTC platform:Decypher the JWT with the secret and make sure it correspond to apikey and userid
ApiRTC platform->>Web Application:Return a Session object
" %}

### How to forge a JWT&#x20;

To understand the JWT format, here is a code sample using the [jsonwebtoken](https://www.npmjs.com/package/jsonwebtoken) authentication module:

```javascript
jsonwebtoken.sign({
    grants: {
      apiRTC_UserAgent_Id: '#YOUR_USER_ID#'
    }
  },
  '#YOUR_SECRET_HERE#',
  {
    header: {
      typ: 'JWT'
    },
    algorithm: 'HS256',
    subject: '#YOUR APIKEY_HERE#',
    audience: 'apiRTC',
    expiresIn: 3600,
    jwtid: uuidv4()
  });
```

* `#YOUR_USER_ID#` is the user identifier used in the external user management system,
* `#YOUR_SECRET_HERE#` is a secret key that you get from the [ApiRTC authentication configuration](https://cloud.apirtc.com/enterprise/users-authentication) interface,
* `#YOUR APIKEY_HERE#` is an apiKey you get from the [ApiRTC console](https://cloud.apirtc.com/enterprise/api).

### Continue reading about JWT Authentication

* [Access token : Using JSON Web Token (JWT) for session authentication](https://apirtc.com/blog/apirtc-access-token-using-json-web-token-jwt-for-session-authentication/)
* [JWT: The Complete Guide to JSON Web Tokens](https://blog.angular-university.io/angular-jwt/)
* [Introduction to JSON Web Tokens](https://jwt.io/introduction)


---

# 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://dev.apirtc.com/apirtc-developer-portal/apirtc-js-library/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.