Create User:
POST https://www.knowi.com/sso/user/create
| Parameter | Type | Description |
| ssoCustomerToken | string | Required. Customer-specific SSO Token to authorize SSO user management. |
| user | string | Required. Email/username of the new or existing user. |
| userGroups[] | array of strings |
An array of groups the user will be associated with. Note: Group will be created if it does not exist. Send an empty array ([]) to remove dissociate the user from all groups. |
| contentFilter | object |
A JSON object to apply a row-level filter on data user is allowed to see. Ex: [{"fieldName": "region", "values":["Canada","Mexico"], "operator":"="}] |
| role | string | Role and permissions to assign the user. Defaults to system user if blank. |
| refresh | bool | If True, the user's properties (i.e. userGroups[], contentFilter, role) will be updated with new values. |
| refreshToken | bool | Defaults to true. When true and the user already exists, a new user token is generated and returned, and the previous token stops working. If set to false, the existing user token is left unchanged (and is not returned). If the flag is false and the user does not exist, a new user will still be created with a new token. See Token lifetimes and rotation. |
Returns:
A user-specific token. Store this for your user within your system.Example:
curl -i -X POST -d "userGroups[]=First Group&userGroups[]=Second Group&user=a@a.com&ssoCustomerToken=9ebdlklfWlYuQXPXanqHxq7ZflklfZ1pGC8Ny8l2is9uNhMie" https://www.knowi.com/sso/user/createCreate Session:
POST https://www.knowi.com/sso/session/create
| Parameter | Type | Description |
| user | string | Required. Email/username of the existing user. |
| userToken | string | Required. Token returned from user creation (/sso/user/create) |
| expiry | integer | Optional. Number of minutes from the token creation datetime until expiration. By default, session tokens expire after 30 minutes. |
Returns:
A session token. It expires after 30 minutes by default, or after the number of minutes passed in the expiry parameter. Creating a new session token for a user invalidates that user's previous one.Example:
curl -i -X POST -d "user=a@a.com&userToken=NUAslkrtRTTFMvscpiislikfyfhsgu491is7plqRvwvJGEgm7JVU8ie&expiry=1440" https://www.knowi.com/sso/session/createDelete User:
POST: https://www.knowi.com/sso/user/remove
| Parameter | Type | Description |
| user | string | Required. Email/username of the existing user. |
| userToken | string | Required. Token returned from user creation (/sso/user/create) |
| ssoCustomerToken | string | Required. Customer-specific SSO Token to authorize SSO user management. |
Update User Filter:
POST: https://www.knowi.com/sso/user/contentfilters/update
| Parameter | Type | Description |
| contentFilter | string |
Required. A JSON object to apply a row-level filter on data user is allowed to see. Ex: [{"fieldName": "region", "values":["Italy"], "operator":"="}] |
| user | string | Required. Email/username of the existing user. |
| ssoCustomerToken | string | Required. Customer-specific SSO Token to authorize SSO user management. |
Example:
curl -i -X POST -d "user=demoSSO@knowi.com&ssoCustomerToken=9ebdlklfWlYuQXPXanqHxq7ZflklfZ1pGC8Ny8l2is9uNhMie&contentFilter=[{\"fieldName\":\"customer\",\"values\":[\"Costco\"],\"operator\":\"=\"}]" https://www.knowi.com/sso/user/contentfilters/updateToken lifetimes and rotation
The SSO flow uses three different tokens. They have different lifetimes and are invalidated in different ways.
| Token | Expires? | How to invalidate it |
| Session token Returned by /sso/session/create |
Yes. 30 minutes by default, or the number of minutes passed in the expiry parameter. |
Call PUT /sso/user/logout with the token. Creating a new session token for the same user also invalidates the previous one, because each user has one active session token. |
| User token Returned by /sso/user/create |
No. It works like a password: Knowi does not store it in readable form, and the user name plus user token are needed to create a session token. | Rotate it. See below. |
| Customer SSO token Used as ssoCustomerToken |
No. | Regenerate or revoke it in Account Settings. This option appears only when SSO token generation is enabled for your account. Contact Knowi support to enable it. Anything signed or encrypted with the old token stops working. |
Rotating a user token
To replace a user's token, call /sso/user/create again for the same user with your ssoCustomerToken and refreshToken=true (the default). Knowi generates a new user token, returns it, and the previous token can no longer be used to create session tokens. The user, along with their groups, role and filters, is kept. Store the new token in your system.
Example:
curl -i -X POST -d "user=a@a.com&ssoCustomerToken=9ebdlklfWlYuQXPXanqHxq7ZflklfZ1pGC8Ny8l2is9uNhMie&refreshToken=true" https://www.knowi.com/sso/user/createTo invalidate every user token, repeat the call for each SSO user. There is no single call that rotates all users at once.
Note: Rotating a user token does not end session tokens that are already open. Those expire on their own, or you can end them with PUT /sso/user/logout.