Ninchat Master Keys
This document describes Ninchat master keys (API keys).
Copyright © Somia Reality Oy. All rights reserved.
- Ninchat Signing and Secure Metadata
- Using JWT with Ninchat Master Keys
- Ninchat Puppets
- Ninchat API Reference
A master key always ultimately belongs to a specific Ninchat user. When the key is used, that master user exerts control over other users or resources.
Ninchat supports two types of master keys: "ninchat"-type keys are used with the algorithms described in Ninchat Signing and Secure Metadata, and "jwt"-type keys are used for creating JWT tokens; see Using JWT with Ninchat Master Keys.
API keys can be created in two ways:
- Using the https://ninchat.com/app/#/x/settings/masterkeys user interface.
- Using the
By default a master key may be used for the following things:
- Authentication and control of puppet users.
- Authorizing access to the master user's resources (such as channels).
A master key may optionally be specific to a realm (aka. organization). Such keys differ from the non-specific ones in the following ways:
- They may not be used with puppets.
- They authorize access only to the specific realm's resources.
- Also the realm's operators may create and delete the keys.
An existing puppet user can be logged in at the Ninchat website by forming a URL:
USER_IDis the Ninchat user id to log in (specify as
-when using JWT).
MASTER_KEY_TYPEis "ninchat" or "jwt".
MASTER_SIGNis the generated signature.
A third-party service's user can be logged in via the embedded Ninchat client
by specifying the
masterUserSign parameters. If the key
type is "ninchat" and an existing user is to be logged in, the
parameter must also be specified. Ninchat user id is never needed if the key
type is "jwt".
If the user needs to be added to a channel, also the
parameter needs to be specified. A single JWT token containing authentication
and authorization claims can be used as both the user and the channel
signature. But if the key type is "ninchat", a separate channel action
signature needs to be generated.
When Ninchat is integrated to a third-party service, secure metadata can be used to communicate arbitrary end user related information to the customer care agent. It typically contains identification of an authenticated user, plus other information that is helpful for the agent during the chat.
Secure metadata is encrypted by the third-party server, using the original encoding or encapsulated in a JWT token. The encrypted string is then passed to the web browser on the page which embeds Ninchat.
Non-secure metadata is specified via the embedded Ninchat client's
audienceMetadata parameter, and secure metadata is included in the "secure"