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.

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

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

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

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:

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 on SDK API server, with server key and userId. Refer to the table below for the correct region code and endpoint.

   Region

   Region code

   Endpoint

   Europe

   eu

   https://apix.eu.amity.co/

   Singapore

   sg

   https://apix.sg.amity.co/ or https://apix.amity.co/

   United States

   us

   https://apix.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 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

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.

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 using the API key and user id. Refer to Get API key section for the instructions on how to get the API key.

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"
}'

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

{
  "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": []
}

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 from the console.

1. Call /api/v3/authentication/token using the server key.

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>'

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

"<autenticationToken>"

3. Call /api/v3/session using the returned token.

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.

{
  "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": []
}

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 and Admin Token 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

• Specify the Certificate Name and Certificate Signing Request (CSR)

• Activate the mTLS feature

Enabling the mTLS feature is optional.

To increase the security of our admin tokens, we have enhanced the ability to generate new admin tokens with shorter expiration time and the ability to revoke admin tokens.

Generating New Admin Access Token

Previously, all generated access tokens had an expiration time of 10 years by default. From now on, the expiration time for all newly generated access tokens will be reduced to 1 year. This new enhancement only affects the newly generated tokens. So if you want a token with a shorter expiration time, you will need to generate a new token through the console.

This is not available for Super Admin.

To retrieve your current admin token:

• In the Console, go to Settings > Admin Users

• Click the ellipses ...next to your user name to retrieve your current admin token.

• Click the Generate button to generate (create) a new token, which will invalidate the existing token.

• Click the Confirm button.

Once the new token is generated, the admin will be notified to get switched from the old token to the new token within 24 hours.

Please remember to generate a new token before it expires. Otherwise, you will get a "token expired" error if you use an expired token for API calls.

Revoke Admin Token

In case the admin token has been compromised, admin users can now revoke their own admin token, and Super Admins can revoke another admin's token. Revoking tokens is done by passing the username parameter.

After revocation, that admin's token becomes invalid and the admin will be automatically logged out of Console. When that admin logs in again, a new token will be generated. The admin must use this new token for future API calls, otherwise they will receive an "Invalid token' error.