Security

The menu dedicated to security asset management such as API Key, Server Key.

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:

Login to your SP Console
Go to Settings -> Integrations
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.

The user must not be a super-admin to be able to generate the key.

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:

Client initiates a call to the backend.
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.
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.

Open Social Plus Console.
On the left menu, select Settings to expand its submenu.
Select Integrations.
On the Integrations page, you will find the apiKey.

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.

Authentication

There are 2 modes of Authentication:

Unsecure mode
Secure mode

Unsecure mode

With secure mode disabled, you can connect directly to the Social Plus server.

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

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.

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

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

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.

Secure Mode

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

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

Provide a userId to get a token for that user

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

Response Body

"<autenticationToken>"

The authentication token will expire after ten minutes.
Banning a user, whether it is on a global or channel level, will not invalidate the 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.

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

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.

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.