Users and access
Use this workflow to review users, assign an access profile, invite a new user, or organise users into teams. Your API key must have permission to manage users in the target company.
List access profiles
Start by finding the profile that represents the permissions you want to grant.
List access profiles
This generated query uses placeholders for required values. Replace them with values available to your API key before running it.
Use collection[].id as <access_profile_id> when inviting a user or updating access.
- cURL
- JavaScript
- Python
curl --request POST https://api.convisoappsec.com/graphql \
--header "x-api-key: $CONVISO_API_KEY" \
--header "content-type: application/json" \
--data '{"query":"query GetPortalUserAccessProfiles($companyId: ID!) {\n portalUserAccessProfiles(companyId: $companyId) {\n collection { id name assetPermissions }\n metadata { currentPage limitValue totalCount }\n }\n}","variables":{"companyId":"<company_id>"}}'
const response = await fetch('https://api.convisoappsec.com/graphql', {
method: 'POST',
headers: {
'content-type': 'application/json',
'x-api-key': process.env.CONVISO_API_KEY,
},
body: JSON.stringify({
query: "query GetPortalUserAccessProfiles($companyId: ID!) {\n portalUserAccessProfiles(companyId: $companyId) {\n collection { id name assetPermissions }\n metadata { currentPage limitValue totalCount }\n }\n}",
variables: {
"companyId": "<company_id>"
},
}),
});
const { data, errors } = await response.json();
if (errors) throw new Error(errors.map(({ message }) => message).join(', '));
console.log(data);
import json
import os
import requests
response = requests.post(
'https://api.convisoappsec.com/graphql',
headers={
'content-type': 'application/json',
'x-api-key': os.environ['CONVISO_API_KEY'],
},
json={
'query': "query GetPortalUserAccessProfiles($companyId: ID!) {\n portalUserAccessProfiles(companyId: $companyId) {\n collection { id name assetPermissions }\n metadata { currentPage limitValue totalCount }\n }\n}",
'variables': json.loads("{\"companyId\":\"<company_id>\"}"),
},
timeout=30,
)
response.raise_for_status()
payload = response.json()
if payload.get('errors'):
raise RuntimeError(payload['errors'])
print(payload['data'])
List users in a company
Use the returned user ID to inspect or change one user's access.
List company users
This generated query uses placeholders for required values. Replace them with values available to your API key before running it.
Use collection[].id as <portal_user_id> in the access operations below.
- cURL
- JavaScript
- Python
curl --request POST https://api.convisoappsec.com/graphql \
--header "x-api-key: $CONVISO_API_KEY" \
--header "content-type: application/json" \
--data '{"query":"query GetPortalUserByCompany($companyId: ID!, $page: Int!, $limit: Int!) {\n portalUserByCompany(companyId: $companyId, page: $page, limit: $limit) {\n collection { id name }\n metadata { currentPage limitValue totalCount }\n }\n}","variables":{"companyId":"<company_id>","page":1,"limit":20}}'
const response = await fetch('https://api.convisoappsec.com/graphql', {
method: 'POST',
headers: {
'content-type': 'application/json',
'x-api-key': process.env.CONVISO_API_KEY,
},
body: JSON.stringify({
query: "query GetPortalUserByCompany($companyId: ID!, $page: Int!, $limit: Int!) {\n portalUserByCompany(companyId: $companyId, page: $page, limit: $limit) {\n collection { id name }\n metadata { currentPage limitValue totalCount }\n }\n}",
variables: {
"companyId": "<company_id>",
"page": 1,
"limit": 20
},
}),
});
const { data, errors } = await response.json();
if (errors) throw new Error(errors.map(({ message }) => message).join(', '));
console.log(data);
import json
import os
import requests
response = requests.post(
'https://api.convisoappsec.com/graphql',
headers={
'content-type': 'application/json',
'x-api-key': os.environ['CONVISO_API_KEY'],
},
json={
'query': "query GetPortalUserByCompany($companyId: ID!, $page: Int!, $limit: Int!) {\n portalUserByCompany(companyId: $companyId, page: $page, limit: $limit) {\n collection { id name }\n metadata { currentPage limitValue totalCount }\n }\n}",
'variables': json.loads("{\"companyId\":\"<company_id>\",\"page\":1,\"limit\":20}"),
},
timeout=30,
)
response.raise_for_status()
payload = response.json()
if payload.get('errors'):
raise RuntimeError(payload['errors'])
print(payload['data'])
Invite a user
The invitation applies the selected access profile in the company scope.
Invite a user with an access profile
This generated mutation uses placeholders for required values. Replace them with values available to your API key before running it.
- cURL
- JavaScript
- Python
curl --request POST https://api.convisoappsec.com/graphql \
--header "x-api-key: $CONVISO_API_KEY" \
--header "content-type: application/json" \
--data '{"query":"mutation CreateInviteUser($input: CreateInviteUserInput!) {\n createInviteUser(input: $input) {\n msg\n }\n}","variables":{"input":{"companyId":"<company_id>","accessProfileId":"<access_profile_id>","emails":["new.user@example.com"],"accesses":{}}}}'
const response = await fetch('https://api.convisoappsec.com/graphql', {
method: 'POST',
headers: {
'content-type': 'application/json',
'x-api-key': process.env.CONVISO_API_KEY,
},
body: JSON.stringify({
query: "mutation CreateInviteUser($input: CreateInviteUserInput!) {\n createInviteUser(input: $input) {\n msg\n }\n}",
variables: {
"input": {
"companyId": "<company_id>",
"accessProfileId": "<access_profile_id>",
"emails": [
"new.user@example.com"
],
"accesses": {}
}
},
}),
});
const { data, errors } = await response.json();
if (errors) throw new Error(errors.map(({ message }) => message).join(', '));
console.log(data);
import json
import os
import requests
response = requests.post(
'https://api.convisoappsec.com/graphql',
headers={
'content-type': 'application/json',
'x-api-key': os.environ['CONVISO_API_KEY'],
},
json={
'query': "mutation CreateInviteUser($input: CreateInviteUserInput!) {\n createInviteUser(input: $input) {\n msg\n }\n}",
'variables': json.loads("{\"input\":{\"companyId\":\"<company_id>\",\"accessProfileId\":\"<access_profile_id>\",\"emails\":[\"new.user@example.com\"],\"accesses\":{}}}"),
},
timeout=30,
)
response.raise_for_status()
payload = response.json()
if payload.get('errors'):
raise RuntimeError(payload['errors'])
print(payload['data'])
Review or change a user's access
Use portalUserAccess to confirm the current profile, then assign a different
profile when responsibilities change. This does not create a new user.
Review a user's current access
This generated query uses placeholders for required values. Replace them with values available to your API key before running it.
- cURL
- JavaScript
- Python
curl --request POST https://api.convisoappsec.com/graphql \
--header "x-api-key: $CONVISO_API_KEY" \
--header "content-type: application/json" \
--data '{"query":"query GetPortalUserAccess($portalUserId: ID!, $companyId: Int!) {\n portalUserAccess(portalUserId: $portalUserId, companyId: $companyId) {\n accessProfile { id name }\n portalUser { id name }\n }\n}","variables":{"portalUserId":"<portal_user_id>","companyId":1}}'
const response = await fetch('https://api.convisoappsec.com/graphql', {
method: 'POST',
headers: {
'content-type': 'application/json',
'x-api-key': process.env.CONVISO_API_KEY,
},
body: JSON.stringify({
query: "query GetPortalUserAccess($portalUserId: ID!, $companyId: Int!) {\n portalUserAccess(portalUserId: $portalUserId, companyId: $companyId) {\n accessProfile { id name }\n portalUser { id name }\n }\n}",
variables: {
"portalUserId": "<portal_user_id>",
"companyId": 1
},
}),
});
const { data, errors } = await response.json();
if (errors) throw new Error(errors.map(({ message }) => message).join(', '));
console.log(data);
import json
import os
import requests
response = requests.post(
'https://api.convisoappsec.com/graphql',
headers={
'content-type': 'application/json',
'x-api-key': os.environ['CONVISO_API_KEY'],
},
json={
'query': "query GetPortalUserAccess($portalUserId: ID!, $companyId: Int!) {\n portalUserAccess(portalUserId: $portalUserId, companyId: $companyId) {\n accessProfile { id name }\n portalUser { id name }\n }\n}",
'variables': json.loads("{\"portalUserId\":\"<portal_user_id>\",\"companyId\":1}"),
},
timeout=30,
)
response.raise_for_status()
payload = response.json()
if payload.get('errors'):
raise RuntimeError(payload['errors'])
print(payload['data'])
Assign a different access profile
This generated mutation uses placeholders for required values. Replace them with values available to your API key before running it.
- cURL
- JavaScript
- Python
curl --request POST https://api.convisoappsec.com/graphql \
--header "x-api-key: $CONVISO_API_KEY" \
--header "content-type: application/json" \
--data '{"query":"mutation UpdatePortalUserAccess($input: UpdatePortalUserAccessInput!) {\n updatePortalUserAccess(input: $input) {\n portalUserAccess {\n accessProfile { id name }\n portalUser { id name }\n }\n }\n}","variables":{"input":{"portalUserId":"<portal_user_id>","companyId":"<company_id>","accessProfileId":"<access_profile_id>"}}}'
const response = await fetch('https://api.convisoappsec.com/graphql', {
method: 'POST',
headers: {
'content-type': 'application/json',
'x-api-key': process.env.CONVISO_API_KEY,
},
body: JSON.stringify({
query: "mutation UpdatePortalUserAccess($input: UpdatePortalUserAccessInput!) {\n updatePortalUserAccess(input: $input) {\n portalUserAccess {\n accessProfile { id name }\n portalUser { id name }\n }\n }\n}",
variables: {
"input": {
"portalUserId": "<portal_user_id>",
"companyId": "<company_id>",
"accessProfileId": "<access_profile_id>"
}
},
}),
});
const { data, errors } = await response.json();
if (errors) throw new Error(errors.map(({ message }) => message).join(', '));
console.log(data);
import json
import os
import requests
response = requests.post(
'https://api.convisoappsec.com/graphql',
headers={
'content-type': 'application/json',
'x-api-key': os.environ['CONVISO_API_KEY'],
},
json={
'query': "mutation UpdatePortalUserAccess($input: UpdatePortalUserAccessInput!) {\n updatePortalUserAccess(input: $input) {\n portalUserAccess {\n accessProfile { id name }\n portalUser { id name }\n }\n }\n}",
'variables': json.loads("{\"input\":{\"portalUserId\":\"<portal_user_id>\",\"companyId\":\"<company_id>\",\"accessProfileId\":\"<access_profile_id>\"}}"),
},
timeout=30,
)
response.raise_for_status()
payload = response.json()
if payload.get('errors'):
raise RuntimeError(payload['errors'])
print(payload['data'])
Organise users into teams
Use teams when access should be managed around a working group.
Create a team
This generated mutation uses placeholders for required values. Replace them with values available to your API key before running it.
- cURL
- JavaScript
- Python
curl --request POST https://api.convisoappsec.com/graphql \
--header "x-api-key: $CONVISO_API_KEY" \
--header "content-type: application/json" \
--data '{"query":"mutation CreateTeam($input: CreateTeamInput!) {\n createTeam(input: $input) {\n team { id label }\n }\n}","variables":{"input":{"companyId":"<company_id>","params":{"label":"Application Security"}}}}'
const response = await fetch('https://api.convisoappsec.com/graphql', {
method: 'POST',
headers: {
'content-type': 'application/json',
'x-api-key': process.env.CONVISO_API_KEY,
},
body: JSON.stringify({
query: "mutation CreateTeam($input: CreateTeamInput!) {\n createTeam(input: $input) {\n team { id label }\n }\n}",
variables: {
"input": {
"companyId": "<company_id>",
"params": {
"label": "Application Security"
}
}
},
}),
});
const { data, errors } = await response.json();
if (errors) throw new Error(errors.map(({ message }) => message).join(', '));
console.log(data);
import json
import os
import requests
response = requests.post(
'https://api.convisoappsec.com/graphql',
headers={
'content-type': 'application/json',
'x-api-key': os.environ['CONVISO_API_KEY'],
},
json={
'query': "mutation CreateTeam($input: CreateTeamInput!) {\n createTeam(input: $input) {\n team { id label }\n }\n}",
'variables': json.loads("{\"input\":{\"companyId\":\"<company_id>\",\"params\":{\"label\":\"Application Security\"}}}"),
},
timeout=30,
)
response.raise_for_status()
payload = response.json()
if payload.get('errors'):
raise RuntimeError(payload['errors'])
print(payload['data'])
For custom access-profile permissions, team updates, removals, and other access operations, use the complete schema.
Contribute to the Docs
Found something outdated or missing? Help us improve the documentation with a quick suggestion or edit.
How to contribute