Skip to content

Personal Access Tokens

Operations Summary

Method Endpoint Description
Core CRUD
GET /api/personal-access-tokens/ List Personal Access Tokens
GET /api/personal-access-tokens/{uuid}/ Retrieve
POST /api/personal-access-tokens/ Create a personal access token
DELETE /api/personal-access-tokens/{uuid}/ Revoke a personal access token
Other Actions
GET /api/personal-access-tokens/available_binding_targets/ List entity types the caller can bind each permission to
GET /api/personal-access-tokens/available_scopes/ List available scopes for PAT creation
POST /api/personal-access-tokens/{uuid}/rotate/ Rotate a personal access token
POST /api/personal-access-tokens/{uuid}/set_network_acl/ Replace the network ACL of a personal access token

Core CRUD

List Personal Access Tokens

1
2
3
4
http \
  GET \
  https://api.example.com/api/personal-access-tokens/ \
  Authorization:"Token YOUR_API_TOKEN"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
from waldur_api_client.client import AuthenticatedClient
from waldur_api_client.api.personal_access_tokens import personal_access_tokens_list # (1)

client = AuthenticatedClient(
    base_url="https://api.example.com", token="YOUR_API_TOKEN"
)
response = personal_access_tokens_list.sync(client=client)

for item in response:
    print(item)
  1. API Source: personal_access_tokens_list
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import { personalAccessTokensList } from 'waldur-js-client';

try {
  const response = await personalAccessTokensList({
  auth: "Token YOUR_API_TOKEN"
});
  console.log('Success:', response);
} catch (error) {
  console.error('Error:', error);
}
Name Type Description
page integer A page number within the paginated result set.
page_size integer Number of results to return per page.

200 -

The response body is an array of objects, where each object has the following structure:

Field Type Description
uuid string (uuid)
name string
token_prefix string
scopes array of strings
allowed_scopes array of objects
allowed_scopes.type string
allowed_scopes.uuid string (uuid)
allowed_scopes.name string
allowed_networks array of strings
expires_at string (date-time)
is_active boolean
last_used_at string (date-time)
last_used_ip any An IPv4 or IPv6 address.
use_count integer
created string (date-time)

Retrieve

1
2
3
4
http \
  GET \
  https://api.example.com/api/personal-access-tokens/a1b2c3d4-e5f6-7890-abcd-ef1234567890/ \
  Authorization:"Token YOUR_API_TOKEN"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
from waldur_api_client.client import AuthenticatedClient
from waldur_api_client.api.personal_access_tokens import personal_access_tokens_retrieve # (1)

client = AuthenticatedClient(
    base_url="https://api.example.com", token="YOUR_API_TOKEN"
)
response = personal_access_tokens_retrieve.sync(
    uuid="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    client=client
)

print(response)
  1. API Source: personal_access_tokens_retrieve
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import { personalAccessTokensRetrieve } from 'waldur-js-client';

try {
  const response = await personalAccessTokensRetrieve({
  auth: "Token YOUR_API_TOKEN",
  path: {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
});
  console.log('Success:', response);
} catch (error) {
  console.error('Error:', error);
}
Name Type Required
uuid string (uuid) ✓

200 -

Field Type Description
uuid string (uuid)
name string
token_prefix string
scopes array of strings
allowed_scopes array of objects
allowed_scopes.type string
allowed_scopes.uuid string (uuid)
allowed_scopes.name string
allowed_networks array of strings
expires_at string (date-time)
is_active boolean
last_used_at string (date-time)
last_used_ip any An IPv4 or IPv6 address.
use_count integer
created string (date-time)

Create a personal access token

1
2
3
4
5
6
7
http \
  POST \
  https://api.example.com/api/personal-access-tokens/ \
  Authorization:"Token YOUR_API_TOKEN" \
  name="my-awesome-personal-access-token" \
  scopes:='[]' \
  expires_at="2023-10-01T12:00:00Z"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
from waldur_api_client.client import AuthenticatedClient
from waldur_api_client.models.personal_access_token_create_request import PersonalAccessTokenCreateRequest # (1)
from waldur_api_client.api.personal_access_tokens import personal_access_tokens_create # (2)

client = AuthenticatedClient(
    base_url="https://api.example.com", token="YOUR_API_TOKEN"
)

body_data = PersonalAccessTokenCreateRequest(
    name="my-awesome-personal-access-token",
    scopes=[],
    expires_at="2023-10-01T12:00:00Z"
)
response = personal_access_tokens_create.sync(
    client=client,
    body=body_data
)

print(response)
  1. Model Source: PersonalAccessTokenCreateRequest
  2. API Source: personal_access_tokens_create
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
import { personalAccessTokensCreate } from 'waldur-js-client';

try {
  const response = await personalAccessTokensCreate({
  auth: "Token YOUR_API_TOKEN",
  body: {
    "name": "my-awesome-personal-access-token",
    "scopes": [],
    "expires_at": "2023-10-01T12:00:00Z"
  }
});
  console.log('Success:', response);
} catch (error) {
  console.error('Error:', error);
}
Field Type Required Description
name string ✓
scopes array of strings ✓
allowed_scopes array of objects Optional list of entity bindings restricting where this token can act. Empty list = no entity restriction.
allowed_scopes.type string ✓
allowed_scopes.uuid string (uuid) ✓
allowed_networks array of strings Optional list of CIDR networks the token may be used from. Bare addresses are widened to /32 or /128. Empty list = no network restriction.
expires_at string (date-time) ✓

201 -

Field Type Description
uuid string (uuid)
name string
token string Plaintext token — shown only once.
scopes array of strings
allowed_scopes array of objects
allowed_scopes.type string
allowed_scopes.uuid string (uuid)
allowed_scopes.name string
allowed_networks array of strings
expires_at string (date-time)
created string (date-time)

Revoke a personal access token

1
2
3
4
http \
  DELETE \
  https://api.example.com/api/personal-access-tokens/a1b2c3d4-e5f6-7890-abcd-ef1234567890/ \
  Authorization:"Token YOUR_API_TOKEN"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
from waldur_api_client.client import AuthenticatedClient
from waldur_api_client.api.personal_access_tokens import personal_access_tokens_destroy # (1)

client = AuthenticatedClient(
    base_url="https://api.example.com", token="YOUR_API_TOKEN"
)
response = personal_access_tokens_destroy.sync(
    uuid="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    client=client
)

print(response)
  1. API Source: personal_access_tokens_destroy
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import { personalAccessTokensDestroy } from 'waldur-js-client';

try {
  const response = await personalAccessTokensDestroy({
  auth: "Token YOUR_API_TOKEN",
  path: {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
});
  console.log('Success:', response);
} catch (error) {
  console.error('Error:', error);
}
Name Type Required
uuid string (uuid) ✓

204 - No response body

Other Actions

List entity types the caller can bind each permission to

For each permission, which TYPE_MAP keys the caller could bind a PAT to.

Drives the create-PAT frontend's type picker. For staff users every type is offered for every permission (they bypass UserRole checks). For other users we return only types where they hold an active role granting the permission directly (the binding then inherits to descendants at request time).

1
2
3
4
http \
  GET \
  https://api.example.com/api/personal-access-tokens/available_binding_targets/ \
  Authorization:"Token YOUR_API_TOKEN"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
from waldur_api_client.client import AuthenticatedClient
from waldur_api_client.api.personal_access_tokens import personal_access_tokens_available_binding_targets_list # (1)

client = AuthenticatedClient(
    base_url="https://api.example.com", token="YOUR_API_TOKEN"
)
response = personal_access_tokens_available_binding_targets_list.sync(client=client)

for item in response:
    print(item)
  1. API Source: personal_access_tokens_available_binding_targets_list
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import { personalAccessTokensAvailableBindingTargetsList } from 'waldur-js-client';

try {
  const response = await personalAccessTokensAvailableBindingTargetsList({
  auth: "Token YOUR_API_TOKEN"
});
  console.log('Success:', response);
} catch (error) {
  console.error('Error:', error);
}
Name Type Description
page integer A page number within the paginated result set.
page_size integer Number of results to return per page.

200 -

The response body is an array of objects, where each object has the following structure:

Field Type
permission string
types array of strings

List available scopes for PAT creation

Return permissions the current user can delegate to a PAT.

Staff users can delegate any permission (they bypass UserRole checks). For other users only the permissions granted by their active roles are offered, plus SUPPORT.ACCESS for support users — mirroring what the create serializer would accept.

1
2
3
4
http \
  GET \
  https://api.example.com/api/personal-access-tokens/available_scopes/ \
  Authorization:"Token YOUR_API_TOKEN"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
from waldur_api_client.client import AuthenticatedClient
from waldur_api_client.api.personal_access_tokens import personal_access_tokens_available_scopes_list # (1)

client = AuthenticatedClient(
    base_url="https://api.example.com", token="YOUR_API_TOKEN"
)
response = personal_access_tokens_available_scopes_list.sync(client=client)

for item in response:
    print(item)
  1. API Source: personal_access_tokens_available_scopes_list
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import { personalAccessTokensAvailableScopesList } from 'waldur-js-client';

try {
  const response = await personalAccessTokensAvailableScopesList({
  auth: "Token YOUR_API_TOKEN"
});
  console.log('Success:', response);
} catch (error) {
  console.error('Error:', error);
}
Name Type Description
page integer A page number within the paginated result set.
page_size integer Number of results to return per page.

200 -

The response body is an array of objects, where each object has the following structure:

Field Type
permission string
description string

Rotate a personal access token

Atomically revoke the old token and create a new one with the same scopes and bindings.

1
2
3
4
http \
  POST \
  https://api.example.com/api/personal-access-tokens/a1b2c3d4-e5f6-7890-abcd-ef1234567890/rotate/ \
  Authorization:"Token YOUR_API_TOKEN"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
from waldur_api_client.client import AuthenticatedClient
from waldur_api_client.api.personal_access_tokens import personal_access_tokens_rotate # (1)

client = AuthenticatedClient(
    base_url="https://api.example.com", token="YOUR_API_TOKEN"
)
response = personal_access_tokens_rotate.sync(
    uuid="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    client=client
)

print(response)
  1. API Source: personal_access_tokens_rotate
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import { personalAccessTokensRotate } from 'waldur-js-client';

try {
  const response = await personalAccessTokensRotate({
  auth: "Token YOUR_API_TOKEN",
  path: {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
});
  console.log('Success:', response);
} catch (error) {
  console.error('Error:', error);
}
Name Type Required
uuid string (uuid) ✓

201 -

Field Type Description
uuid string (uuid)
name string
token string Plaintext token — shown only once.
scopes array of strings
allowed_scopes array of objects
allowed_scopes.type string
allowed_scopes.uuid string (uuid)
allowed_scopes.name string
allowed_networks array of strings
expires_at string (date-time)
created string (date-time)

Replace the network ACL of a personal access token

Replace the token's source-network allowlist.

A dedicated action rather than PATCH: update/partial_update stay disabled on this viewset, and the change gets its own audit event.

1
2
3
4
5
http \
  POST \
  https://api.example.com/api/personal-access-tokens/a1b2c3d4-e5f6-7890-abcd-ef1234567890/set_network_acl/ \
  Authorization:"Token YOUR_API_TOKEN" \
  allowed_networks:='[]'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
from waldur_api_client.client import AuthenticatedClient
from waldur_api_client.models.personal_access_token_network_acl_request import PersonalAccessTokenNetworkAclRequest # (1)
from waldur_api_client.api.personal_access_tokens import personal_access_tokens_set_network_acl # (2)

client = AuthenticatedClient(
    base_url="https://api.example.com", token="YOUR_API_TOKEN"
)

body_data = PersonalAccessTokenNetworkAclRequest(
    allowed_networks=[]
)
response = personal_access_tokens_set_network_acl.sync(
    uuid="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    client=client,
    body=body_data
)

print(response)
  1. Model Source: PersonalAccessTokenNetworkAclRequest
  2. API Source: personal_access_tokens_set_network_acl
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
import { personalAccessTokensSetNetworkAcl } from 'waldur-js-client';

try {
  const response = await personalAccessTokensSetNetworkAcl({
  auth: "Token YOUR_API_TOKEN",
  path: {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  body: {
    "allowed_networks": []
  }
});
  console.log('Success:', response);
} catch (error) {
  console.error('Error:', error);
}
Name Type Required
uuid string (uuid) ✓
Field Type Required
allowed_networks array of strings ✓

200 -

Field Type Description
uuid string (uuid)
name string
token_prefix string
scopes array of strings
allowed_scopes array of objects
allowed_scopes.type string
allowed_scopes.uuid string (uuid)
allowed_scopes.name string
allowed_networks array of strings
expires_at string (date-time)
is_active boolean
last_used_at string (date-time)
last_used_ip any An IPv4 or IPv6 address.
use_count integer
created string (date-time)