Managing scopes & access via API

Until the new spaces UI concept is available people need to create scopes via the API. This is a guide that leads you through the calls needed for it.

Preferences

Token of a user / service-user which has admin role assigned → <yourToken>
The base URL of your application → <baseUrl>

To get the token and the URL check this: How to get a Token for our APIs

Creating a scope

First, you need to create the space object itself. This can be done with this cURL. Just replace the following placeholders: <baseUrl> / <yourToken> / <scopeName>

curl --location 'https://gateway.<baseUrl>/scope-management/graphql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <yourToken>' \
--data '{"query":"mutation CreateScope($name: String!) {\n  createScope(name: $name) {\n    id\n    name\n  }\n}","variables":{"name":"<scopeName>"}}'

This should respond with the following successful response with your replaced <scopeName> and a new unique <scopeId>:

{
    "data": {
        "createScope": {
            "id": "<scopeId>",
            "name": "<scopeName>"
        }
    }
}

The scope is now created but no one has access to it. For this, you need to create a scopeAccess object

Creating scope access

The Scope Access object defines who has access to a scope and which type of access it is. A scope can have multiple scope access objects. The scope access contains:

the <entityType> (GROUP or USER)
the <entityId> which should have access to the scope (userId or groupId)
the <accessType> (READ or WRITE)
READ can only query data of this scope, WRITE can only insert new data, update data, and delete data.

The cURL for creating this entity is the following. Replace again the values needed for the CURL: <baseUrl> / <yourToken> / <scopeId> / <entityType> / <entityId> / <accessType>

curl --location 'https://gateway.<baseUrl>/scope-management/graphql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <yourToken>' \
--data '{"query":"mutation CreateScopeAccess($accessType: String!, $entityId: String!, $entityType: String!, $scopeId: String!, $skipUserCheck: Boolean) {\n  createScopeAccess(accessType: $accessType, entityId: $entityId, entityType: $entityType, scopeId: $scopeId, skipUserCheck: $skipUserCheck) {\n    scopeId\n    type\n    entityType\n    entityId\n  }\n}","variables":{"accessType":"<accessType>","entityId":"<entityId>","entityType":"<entityType>","scopeId":"<scopeId>"}}'

The successful cURL should give you the following response:

AccessType WRITE does not implicit give you READ allowance. If you want to give to an entity (User or Group) READ and WRITE access you need to create two scope access objects -> one with READ and one with WRITE for the same entity.

Removing scope access

If a scope access has been created wrongly or anything you want to change anything with previously created accesses, you can use the following cUrl.

Just replace the values analog to the creating query.
<baseUrl> / <yourToken> / <scopeId> / <entityType> / <entityId> / <accessType>

The successful response should look like this:

Query all Scopes

The following call returns all scopes. Replace the values needed for the CURL: <baseUrl> / <yourToken>

The successful cURL should give you the following response:

Query Scopes with its access configuration

The following call returns the scopes. Replace the values needed for the CURL: <baseUrl> / <yourToken>

The successful cURL should give you the following response:

Query Scopes assigned to a User

The following call returns all scopes for the user the access token used belongs to. Replace the values needed for the CURL: <baseUrl> / <yourToken>

The successful cURL should give you the following response:

Delete Scopes

Scopes can be delted as follows, they wont be deletable if they still contain Content. So content must be moved out of a scope or deleted.

Conclusion

Now the entities that have access to this scope and also to the knowledge-base app should be able to see this scope in the UI.

People with WRITE access can select this scope to upload data.
People with READ access can see the data in the table below.

Author	@Adrian Gugger