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

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