# Security

## Use the Server Key to securely authenticate your client with social.plus Cloud server

With secure mode off, social.plus SDK generates an access token on the client side when given an `userId` and `apiKey`. This can lead to malicious users abusing the endpoint and spying on someone else's session.

With secure mode on, an additional authentication token generated from your own backend server using a separate Server Key is required. You must turn on secure mode in your production system, or the system will be vulnerable to such an **attack.**

## **How to generate a server key**

social.plus provides a way to get the server key easily via the SP Console as follows:

1. Login to your SP Console
2. Go to Settings -> Integrations
3. Enable secure mode via the toggle.

<figure><img src="https://2352509137-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MX0mOAVWkotGme0iRzu%2Fuploads%2FD8w5A5ga5RB7KxRilh6G%2FScreenshot%202567-11-13%20at%2010.47.23%20AM.png?alt=media&#x26;token=3d6cf7d1-00fb-485b-a6c0-2a54ef2dba46" alt=""><figcaption></figcaption></figure>

4\. Click "Generate new server key" to generate your server key

<figure><img src="https://2352509137-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MX0mOAVWkotGme0iRzu%2Fuploads%2FbClZCNaJn2KbxJLE626l%2FScreenshot%202567-11-13%20at%2010.48.33%20AM.png?alt=media&#x26;token=f0e8c9c6-eed1-42db-a094-e368d57b051d" alt=""><figcaption></figcaption></figure>

5\. A warning message will pop up. Please ensure to read it and be aware of the impact.

<figure><img src="https://2352509137-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MX0mOAVWkotGme0iRzu%2Fuploads%2FjWDWj6F2T9CUa9VnouoY%2FScreenshot%202567-11-13%20at%2010.49.21%20AM.png?alt=media&#x26;token=b65b364c-1ca0-4cfe-96d2-656edf26df71" alt=""><figcaption></figcaption></figure>

6\. The server key will be shown, please copy and securely store it in your backend system. **The key will only be shown once.**

<figure><img src="https://2352509137-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MX0mOAVWkotGme0iRzu%2Fuploads%2FpEbJ27W4C9TWR1w7q238%2FScreenshot%202567-11-13%20at%2010.50.00%20AM.png?alt=media&#x26;token=9fc70b1b-4916-434c-ad5e-d959ba804ae6" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
The user must not be a super-admin to be able to generate the key.
{% endhint %}

## **How to use server key to create auth token**

Once secure mode is enabled and the server key is generated, all client authentication requests will require an authentication token. Your backend server will need to make a server-to-server call while passing the server key into the social.plus server to get the authentication token. Please follow the following steps to generate an auth token:

<figure><img src="https://2352509137-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MX0mOAVWkotGme0iRzu%2Fuploads%2FL8JrNxtBqwRhHJOLu9D3%2Fauth_token_diagram.png?alt=media&#x26;token=c2060b8a-3145-4a2e-92f1-cc9bcbfa1569" alt=""><figcaption></figcaption></figure>

1. Client initiates a call to the backend.
2. Client's servers make a request to endpoint [`https://apix.<region code>.amity.co/api/v4/authentication/token`](https://apidocs.amity.co/#/Authentication/post_api_v4_authentication_token) on SDK API server, with `server key` and `userId`. Refer to the table below for the correct region code and endpoint.\\

   <table><thead><tr><th width="237.8459279413758">Region</th><th width="180.90037663118443">Region code</th><th>Endpoint</th></tr></thead><tbody><tr><td>Europe</td><td>eu</td><td>https://apix.eu.amity.co/</td></tr><tr><td>Singapore</td><td>sg</td><td>https://apix.sg.amity.co/ or<br>https://apix.amity.co/</td></tr><tr><td>United States</td><td>us</td><td>https://apix.us.amity.co/</td></tr></tbody></table>

   {% hint style="info" %} For EU and US, you need to specify the region in the endpoint link. For SG, however, it is optional. {% endhint %}
3. Receive the auth token back and find a way to pass it up from the server side to the client-side and give it to the SDK.

### Use your auth token in your SDK

To use auth token on the client side, please see the Getting Started guide.

## **How to get API key** <a href="#get-api-key" id="get-api-key"></a>

An API key will be provided when you create the application.

1. Open **social.plus Console**.
2. On the left menu, select **Settings** to expand its submenu.
3. Select **Integrations**.
4. On the Integrations page, you will find the apiKey.

<figure><img src="https://2352509137-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MX0mOAVWkotGme0iRzu%2Fuploads%2FtEfCPCrmwaMdUUBEGGyX%2Fimage.png?alt=media&#x26;token=7144c069-1c11-48f4-bad1-420f47712c6e" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
API key does not contain any information of who the user is. It only contains the `networkId` of the network that the user is in.
{% endhint %}

## **Authentication**

There are 2 modes of Authentication:

1. Unsecure mode
2. Secure mode

### **Unsecure mode**

With secure mode disabled, you can connect directly to the social.plus server.

1\. Call [/api/v3/session](https://api-docs.amity.co/#/Session/post_api_v3_sessions) using the API key and user id. Refer to [Get API key](#get-api-key) section for the instructions on how to get the API key.

```bash
curl -X 'POST' \
  'https://apix.<region>.amity.co/api/v3/sessions' \
  -H 'accept: application/json' \
  -H 'x-api-key: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "userId": "string",
  "deviceId": "string",
  "displayName": "string"
}'
```

{% hint style="info" %}
The request body contains information about user and devices that he/she use to connect to. If `displayName` is provide, that user display is updated as well.

If `userId` doesn't exists, new user will be created.
{% endhint %}

2\. In the Responses, you will find that the server will return an access token in the Response body.

{% code title="Response Body" %}

```json
{
  "accessToken": "<accessToken>",
  "refreshToken": "<refreshToken>",
  "users": [
    {
      "_id": "<userId>",
      "path": "<userPath>",
      "updatedAt": "2022-07-20T09:59:40.854Z",
      "createdAt": "2022-07-20T09:59:40.684Z",
      "isDeleted": false,
      "displayName": "string",
      "userId": "string",
      "metadata": {},
      "roles": [],
      "permissions": [],
      "flagCount": 0,
      "hashFlag": null,
      "avatarFileId": null,
      "isGlobalBan": false
    }
  ],
  "files": []
}
```

{% endcode %}

{% hint style="info" %}
Access token will be valid for 30 days. However, it will be invalidated if a different user will use the same token to register the same device.
{% endhint %}

### Secure Mode

With secure mode enabled, it provides an additional layer of security because it requires server-level authentication.

If Secure mode is enabled, you will need the server key. Refer to our documentation on [How to generate the server key](#how-to-generate-a-server-key) from the console.

1\. Call [/api/v3/authentication/token](https://api-docs.amity.co/#/Authentication/get_api_v3_authentication_token) using the server key.

```bash
curl -X 'GET' \
  'https://apix.<region>.amity.co/api/v3/authentication/token?userId=<userId>' \
  -H 'accept: application/json' \
  -H 'x-server-key: <your-server-key>'
```

{% hint style="info" %}
Provide a `userId` to get a token for that user
{% endhint %}

2\. The server will return an authentication token in the Response body.

{% code title="Response Body" %}

```json
"<autenticationToken>"
```

{% endcode %}

{% hint style="info" %}

1. The authentication token will expire after ten minutes.
2. Banning a user, whether it is on a global or channel level, will not invalidate the token.
   {% endhint %}

3\. Call [/api/v3/session](https://api-docs.amity.co/#/Session/post_api_v3_sessions) using the returned token.

```bash
curl -X 'POST' \
  'https://apix.<region>.amity.co/api/v3/sessions' \
  -H 'accept: application/json' \
  -H 'x-api-key: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "userId": "<userId>",
  "deviceId": "string",
  "displayName": "string",
  "authToken": "<autenticationToken>"
}'
```

4\. In the Responses section, you will find that the server will return an access token in the Response body.

{% code title="Response Body" %}

```json
{
  "accessToken": "<accessToken>",
  "refreshToken": "<refreshToken>",
  "users": [
    {
      "_id": "<userId>",
      "path": "<userPath>",
      "updatedAt": "2022-07-20T09:59:40.854Z",
      "createdAt": "2022-07-20T09:59:40.684Z",
      "isDeleted": false,
      "displayName": "string",
      "userId": "string",
      "metadata": {},
      "roles": [],
      "permissions": [],
      "flagCount": 0,
      "hashFlag": null,
      "avatarFileId": null,
      "isGlobalBan": false
    }
  ],
  "files": []
}
```

{% endcode %}

{% hint style="info" %}

1. Access token is different from the authentication token returned when calling [/api/v3/authentication/token](https://api-docs.amity.co/#/Authentication/get_api_v3_authentication_token).
2. Access token will be valid for 30 days. However, it will be invalidated if a different user will use the same token to register the same device.
   {% endhint %}

## mTLS Certificate

Mutual Transport Layer Security or mTLS, is a two-way mutual authentication technique. It helps two parties to authenticate at both ends of a network if they have the correct private key. mTLS ensures that the people at both ends of a network connection are who they claim to be.

[Authentication Token](#how-to-generate-a-server-key) and [Admin Token](https://docs.social.plus/analytics-and-moderation/console/settings/security/admin-token-management) will be protected by mTLS and provide an extra layer of security.

### How to Enable mTLS Certificate

* In the **Console**, go to **Settings** > **Security** tab
* Click **+Create Certificate** option to create the certificate

{% hint style="info" %}

* In order to use this feature, you must first enable "secure mode."
* There is a maximum upload of 2 certificates.
  {% endhint %}

- Specify the **Certificate** **Name** and **Certificate Signing Request (CSR)**

<figure><img src="https://2352509137-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MX0mOAVWkotGme0iRzu%2Fuploads%2FnAHJt4OSglnlGBGsgCGn%2FScreenshot%202567-11-13%20at%2010.53.14%20AM.png?alt=media&#x26;token=68fe382e-0371-4edb-9e9f-85a32deb5243" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}

* Certificate Name and Certificate Signing Request fields are mandatory.

* Certificate Name can be up to 30 characters.
  {% endhint %}

* Activate the mTLS feature

<figure><img src="https://2352509137-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MX0mOAVWkotGme0iRzu%2Fuploads%2FzyW2MOEpSrmfBZ7Qq9qd%2FScreenshot%202567-11-13%20at%2010.54.07%20AM.png?alt=media&#x26;token=03fd1b54-4340-4c7f-914a-96afdf6735a9" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
We strongly recommend that you enable the mTLS feature only after the certificate has been created.
{% endhint %}

> Enabling the mTLS feature is optional.