# Security ## Use Server Key to securely authenticate your client with Amity Social Cloud server With secure mode off, Amity SDK generates an access token on the client side when given a `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 that is 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 kind of attack.** ## **How to generate a server key** Amity provides a way to get the server key easily via the ASC Console as followed: 1. Login to your ASC Console 2. Go to Setting -> Security 3. Enable secure mode via the toggle. ![](/files/-MeTrAwDXQte3yZh7Wat) 4\. Click "Generate new server key" to generate your server key ![](/files/-MeTrO5KHPKySOvYyDeP) 5\. Click Continue (please make sure you read the warning message and are aware of the impact) ![](/files/-MeTrXXBZAcIXhwyF0wn) 6\. The server key will be shown, please copy and securely store into your backend system. **The key will only be shown once.** ![](/files/-MeTrdvpRsMkhJphdzfV) {% hint style="info" %} 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 server key is generated, all client authentication request will require an authentication token and your backend server will need to make a server-to-server call, while passing server key into Amity Social Cloud server in order to get the authentication token. Please follow the following steps to generate auth token:
1. Client initiates a call to the backend. 2. Client's servers make a request to endpoint [`https://api..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.
RegionRegion codeEndpoint
Europeeuhttps://api.eu.amity.co/
Singaporesghttps://api.sg.amity.co/ or
https://api.amity.co/
United Statesushttps://api.us.amity.co/

For EU and US, you need to specify the region in the endpoint link. For SG, however, it is optional.

3. Receive the auth token back and find a way to pass it up from server-side to 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** An API key will be provided when you create the application. 1. Open **Amity Social Cloud Console**. 2. On the left menu, select **Settings** to expand its submenu. 3. Select **Security**. 4. On the Security page, you will find the apiKey. ![Get apiKey](/files/m5NJMAaNZJ8Ilaz8rpdV) {% 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 Amity 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://api..amity.co/api/v3/sessions' \ -H 'accept: application/json' \ -H 'x-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": "", "refreshToken": "", "users": [ { "_id": "", "path": "", "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 one day. 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](/~/changes/5GVz91dkzloMulIORPZq/analytics-and-moderation/console/settings/security.md#how-to-generate-a-server-key) from 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://api..amity.co/api/v3/authentication/token?userId=' \ -H 'accept: application/json' \ -H 'x-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 "" ``` {% endcode %} {% hint style="info" %} 1. 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://api..amity.co/api/v3/sessions' \ -H 'accept: application/json' \ -H 'x-api-key: ' \ -H 'Content-Type: application/json' \ -d '{ "userId": "", "deviceId": "string", "displayName": "string", "authToken": "" }' ``` 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": "", "refreshToken": "", "users": [ { "_id": "", "path": "", "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](/~/changes/5GVz91dkzloMulIORPZq/analytics-and-moderation/console/settings/security/admin-token-management.md) 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)**

Provide certificate details

{% 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
{% 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. --- # 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://docs.social.plus/~/changes/5GVz91dkzloMulIORPZq/analytics-and-moderation/console/settings/security.md?ask= ``` 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.