Context of this document: The Flip Sync API for users and channels
Working closely with our customers, we have seen common patterns in using the Sync API that lead to hurdles and errors.
To make sending data as easy as possible, we put together five common hurdles or errors our customers face during technical onboarding. This guide will help you save time in these typical problems so you can complete the onboarding process fast (please consider that only the required fields are present in the following JSON examples).
Important to know
-
Since the Sync API works asynchronously for all POST requests you will receive from our server, the response
HTTP 202 Accepted
(unless an error occurs during the validation of the request URL and of the sent JSON. In this case, the response will beHTTP 400 Bad Request
).To track asynchronous errors, every API request has a
request_context
that identifies the request. You can set a value for therequest_context
or leave it unspecified (in the latter case, a unique random value will be assigned to it).To get information about the status of your request, you can give the
request_context
as a path parameter for the endpoint/api/external/v1/requests/{request_context}
. If an error occurs, you can get information about the error by sending a request to the endpoint/api/external/v1/requests/{request_context}/errors
. -
The identifiers of a user are
username
andexternal_id
. The identifiers of a channel aregroup_id
(internal ID created automatically by the Flip backend) andexternal_id
. -
The old Flip
groups
are now calledchannels
. To avoid breaking changes in the API, we still use the wordgroup(s)
for all endpoint and parameter names.
Password policy errors
Every customer account on Flip has a default password policy:
- The password must not match the last three passwords of a user, and
- the password should have a minimum length of 8 characters.
- the password cannot be the same as the username
(Our customers can choose the password policy on Flip. Ask the people responsible for your company's “Flip” project about the specific password policy that your colleagues picked.)
The issue
Every time you send a password that does not follow the policy, an error occurs, and the password will not be updated.
Assuming that you have the default password policy:
-
When you send a password that matches the last three passwords of a user, you will get the following error:
{ "errors": [ { "error_cause": "Invalid password history: Invalid password: must not be equal to any of last 3 passwords.", "error_name": "identity_provider", "item": { "user_external_id": "7170346245" }, "reported_at": "2022-21-01T08:05:48.975425Z" } ], "next_cursor": { "after": "rO0A.......NKUA==", "has_more": false } }
-
When you send a password that does not match the eight characters, you will get the following error:
{ "errors": [ { "error_name": "identity_provider", "error_cause": "Password policy not met: Invalid password: minimum length 8.", "reported_at": "2022-12-01T15:34:29.928182Z", "item": { "user_external_id": "yxcvasdf" } } ], "next_cursor": { "after": "rO0A....\\u003d", "has_more": false } }
The solution
To solve the problem, we suggest changing the approach regarding the process of assigning a password:
- Build logic for creating an initial password for the same user and use this logic for all users. This logic can be simple, like setting the password equal to the username (which we don’t recommend), or more complicated, like the employee ID + date of the user's creation/update.
- Every logic has some advantages and disadvantages. That is why we suggest sending the password only for the user's first log in and setting it as temporary.
Create or change users’ and channels’ external_id
Usually, the first users and channels on test and production systems are created manually in the Flip app. The external_id
is the identifier of an object that the client sets and uses to do CRUD operations using the Sync API.
The issue
Situations:
- Since users and channels created in the Flip app don’t have an
external_id
, you cannot update or delete them using the Sync API unless you assign them one. - Sometimes, you may want to change the
external_id
of a user or a channel.
You can create or update an external_id
using the Sync API in both situations.
The solution
Every user has a username
, and every channel has an “internal ID”, a UUID automatically set by the Flip backend. Both username and “internal ID” are Flip identifiers for the objects.
You can use both to map the object to an external_id
:
- Use the endpoints
/api/external/sync/v3/users
or/api/external/v1/sync/groups
to get all users or all channels. - Identify the user or channel that you want to update or delete and copy in the JSON file the value of the key
username
(e.g., “test_user”) for users or the value of the keyname
(e.g., “Test Channel”) andid
(e.g., “306d…2d8f”) for the channels.
For users, choose an external_id
(e.g., “foo”) and send the following JSON example:
{
"users": [
{
"external_id": "foo",
"first_name": "Test",
"last_name": "User",
"system_role": "USER",
"tags": [
],
"username": "test_user"
}
]
}
For channels, choose an external_id
(e.g., “bar”) and send the following JSON example:
{
"groups": [
{
"external_id": "bar",
"group_id": "306d...2d8f",
"name": "Test_Channel"
}
]
}
Now, the user or the channel has the wanted external_id
.
group_id is ignored if the sent external_id is already associated with another channel
As you can see in the previous chapter, you can map an external_id
to a channel sending the group_id
.
However, there are some cases in which the sent group_id
will be ignored. This happens when you send an external_id
that is already associated with a channel name
. Our backend understands this as trying to update channel attributes other than the name
and the external_id
.
The typical use case regards the deletion of channels. To cover the edge case of retrieving data falsely deleted, we use a so-called “soft deletion”. This means that users and channels can be retrieved without losing data (i.e., chat content, channel content, etc.). However, this can cause a channel to be present twice. After the deletion of a channel, a new one with the same name was created manually in the app, and now you want to assign an external_id using the group_id.
The issue
Take a look at this use case:
-
You create the following channel using the Sync API:
Name group_id external_id News from the Headquarters bfa5f3f1-8813-4900-b6c0-bedeef40e7a3 news_from_the_headquarters -
After some tests, you decide to delete it.
-
Your project manager creates a new channel in the Flip app, “News from the Headquarters”, to share information with all headquarters employees.
Name group_id News from the Headquarters 4148b546-76fb-11ed-a1eb-0242ac120002 -
Some information is shared in the channel.
-
You want to add many users to this channel using the Sync API. To achieve that, you need to assign to this channel an
external_id
. You send the following JSON file to map the channel to anexternal_id
:{ "groups": [ { "external_id": "news_from_the_headquarters", "group_id": "4148b546-76fb-11ed-a1eb-0242ac120002", "name": "News from the Headquarters" } ] }
-
By doing that, the
group_id
you sent will be ignored since our backend understands your request as a try to reactivate the deleted channel that already has anexternal_id
. Consequently, you now have two channels with the same name:Name group_id external_id News from the Headquarters 4148b546-76fb-11ed-a1eb-0242ac120002 News from the Headquarters bfa5f3f1-8813-4900-b6c0-bedeef40e7a3 news_from_the_headquarters
The solution
Follow these steps:
-
Change the
external_id
of the channel that was retrieved by sending the following JSON file:{ "groups": [ { "external_id": "false_id", "group_id": "bfa5f3f1-8813-4900-b6c0-bedeef40e7a3", "name": "News from the Headquarters" } ] }
-
Delete the channel:
{ "groups": [ { "external_id": "false_id" } ] }
-
Map the channel created in the Flip app with the desired
external_id
:{ "groups": [ { "external_id": "news_from_the_headquarters", "group_id": "4148b546-76fb-11ed-a1eb-0242ac120002", "name": "News from the Headquarters" } ] }
Now you have the correct channel with the desired external_id
.
Federated identity '…' is not configured for a tenant
The issue
You want the user to log in using Single Sign On (SSO). To set up the identity provider for the user, you send a POST request to the endpoint /api/external/sync/v3/users
with the identity_provider
field:
{
"users": [
{
"external_id": "foo",
"first_name": "Test",
"last_name": "User",
"system_role": "USER",
"tags": [
],
"username": "test_user",
"login": {
"identity_provider": {
"alias": "saml-azure",
"user_id": "test_user",
"username": "test_user"
}
}
}
]
}
You will get by the endpoint /api/external/v1/requests/{request_context}/errors
the following error:
{
"errors": [
{
"error_name": "validation",
"error_cause": "Federated identity 'saml-azure' is not configured for tenant.",
"reported_at": "2022-12-18T02:45:51.702973Z",
"item": {
"user_external_id": "foo"
}
}
],
"next_cursor": {
"after": "rO0N.......1u003d",
"has_more": false
}
}
The solution
The error is caused by the fact that your company account does not have an identity provider called saml-azure
set up.
To solve the problem, you need to contact Flip so that an identity provider can be set up for your company account.
No channel with the given ID exists
The issue
If you send the following POST request to /api/external/v1/sync/groups
with a group_id
that does not exist:
{
"groups": [
{
"external_id": "bar",
"group_id": "0027....fe2d8f", // assume this id is false
"name": "Test_Channel"
}
]
}
You will get the following error:
{
"errors": [
{
"error_name": "not_found",
"error_cause": "No group with group ID '0027.......fe2d8f' exists.",
"reported_at": "2022-12-20T14:47:47.014606Z",
"item": {
"group_external_id": "foo"
}
}
],
"next_cursor": {
"after": "rO0A.......\\u003d",
"has_more": false
}
}
The solution
There is only a real solution to the problem if you send an existing group_id
.
When this error occurs, the client’s intention is usually not to assign an external_id
to a channel sending the group_id
(see other cases in this article).
Instead, the client wants to create a new channel and supposes a group_id
should be set. The group_id
is an internal ID set by the Flip backend only, and it is not required to create a channel.
Comments
0 comments
Please sign in to leave a comment.