> For the complete documentation index, see [llms.txt](https://support.goodaccess.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.goodaccess.com/configuration-guides/features/api-integration/api-reference/tokens.md). # Tokens ## Token Scopes To define what a token can access, you must assign it specific **Scopes**. Each scope grants permission for a particular action or set of data. {% hint style="danger" %} **Principle of Least Privilege:** Always grant only the scopes necessary for the specific integration. For example, a logging integration should only have `*-logs.read` scopes. {% endhint %}
Click to expand the full list of Scopes | Scope | Description | | ------------------------------------------ | --------------------------------------------- | | **Members** | | | `members.create` | Create (invite) a new team member | | `members.read` | Read a specific team member detail | | `members.read-all` | List all team members | | `members.update` | Update a team member | | `members.delete` | Delete a team member | | `members.disconnect` | Disconnect a team member’s active VPN session | | **Groups** | | | `groups.create` | Create a new member group | | `groups.read` | Read a specific member group detail | | `groups.read-all` | List all member groups | | `groups.update` | Update a member group | | `groups.delete` | Delete a member group | | **Systems** | | | `systems.create` | Create a new system | | `systems.read` | Read a specific system detail | | `systems.read-all` | List all systems | | `systems.update` | Update a system | | `systems.delete` | Delete a system | | **System Groups** | | | `system-groups.create` | Create a new system group | | `system-groups.read` | Read a specific system group detail | | `system-groups.read-all` | List all system groups | | `system-groups.update` | Update a system group | | `system-groups.delete` | Delete a system group | | **Access Cards** | | | `access-cards.create` | Create a new access card | | `access-cards.read` | Read a specific access card detail | | `access-card.read-all` | List all access cards | | `access-cards.update` | Update an access card | | `access-cards.delete` | Delete an access card | | **Relations** | | | `member-group-relation.add` | Add a member to a group | | `member-group-relation.delete` | Remove a member from a group | | `member-ac-relation.add` | Add a member to an access card | | `member-ac-relation.delete` | Remove a member from an access card | | `group-access-card-relation.add` | Assign an access card to a member group | | `group-access-card-relation.delete` | Remove an access card from a member group | | `system-system-group-relation.add` | Add a system to a system group | | `system-system-group-relation.delete` | Remove a system from a system group | | `system-ac-relation.add` | Add a system to an access card | | `system-ac-relation.delete` | Remove a system from an access card | | `system-group-access-card-relation.add` | Assign an access card to a system group | | `system-group-access-card-relation.delete` | Remove an access card from a system group | | **Gateways** | | | `gateways.read` | Read a specific gateway detail | | `gateway.read-all` | List all gateways | | **Devices** | | | `devices.read` | Read a specific device detail | | `devices.read-all` | List all devices | | `devices.delete` | Delete a device | | **Tokens** | | | `token.create` | Create a new API token | | `token.read` | Read a specific API token detail | | `token.read-all` | List all API tokens | | `token.delete` | Delete an API token | | **Logs** | | | `gateway-log.read` | Read gateway-level logs | | `system-logs.read` | Read system-level logs | | `threat-blocker-logs.read` | Read threat blocker logs | | `device-posture-check-logs.read` | Read device posture check logs | | `admin-logs.read` | Read admin activity / audit logs |
## GET /api/v1/tokens > Fetch All Tokens ```json {"openapi":"3.0.0","info":{"title":"GoodAccess Customer","version":"1.0.0"},"tags":[{"name":"Tokens"}],"servers":[{"url":"https://integration.goodaccess.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}},"paths":{"/api/v1/tokens":{"get":{"tags":["Tokens"],"summary":"Fetch All Tokens","responses":{"200":{"description":"OK","headers":{"Content-Type":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}}}}}}} ``` ## GET /api/v1/token/{tokenId} > Fetch Token by its ID ```json {"openapi":"3.0.0","info":{"title":"GoodAccess Customer","version":"1.0.0"},"tags":[{"name":"Tokens"}],"servers":[{"url":"https://integration.goodaccess.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}},"paths":{"/api/v1/token/{tokenId}":{"get":{"tags":["Tokens"],"summary":"Fetch Token by its ID","parameters":[{"in":"path","name":"tokenId","schema":{"type":"string"},"required":true,"description":"UUID of the token"}],"responses":{"200":{"description":"OK","headers":{"Content-Type":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object"}}}}}}}}} ``` ## POST /api/v1/token > Create a new Token ```json {"openapi":"3.0.0","info":{"title":"GoodAccess Customer","version":"1.0.0"},"tags":[{"name":"Tokens"}],"servers":[{"url":"https://integration.goodaccess.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}},"paths":{"/api/v1/token":{"post":{"tags":["Tokens"],"summary":"Create a new Token","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Name of the token"},"expires_at":{"type":"string","description":"Expiration date of the token (format 'Y-m-d H:i:s')"},"allowed_ips":{"type":"array","description":"List of IP addresses allowed to use this token. If empty, all IPs are allowed.","items":{"type":"string"}},"allowed_scopes":{"type":"array","description":"List of scopes (permissions) granted to this token. Each scope corresponds to a specific API action.\n","items":{"type":"string","enum":["token.create","token.read","token.delete","token.read-all","members.disconnect","device-posture-check-logs.read","threat-blocker-logs.read","admin-logs.read","devices.read-all","devices.delete","devices.read","group-access-card-relation.delete","group-access-card-relation.add","member-group-relation.delete","member-group-relation.add","system-group-access-card-relation.delete","system-group-access-card-relation.add","system-system-group-relation.delete","system-system-group-relation.add","system-ac-relation.delete","system-ac-relation.add","member-ac-relation.delete","member-ac-relation.add","groups.read-all","system-groups.read-all","access-card.read-all","gateway.read-all","system.read-all","gateway-log.read","members.read-all","system-groups.delete","system-groups.update","system-groups.read","system-groups.create","groups.delete","groups.update","groups.read","groups.create","systems.delete","systems.update","systems.read","systems.create","system-logs.read","access-cards.delete","access-cards.update","access-cards.read","access-cards.create","gateways.read","members.delete","members.update","members.read","members.create"]}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Validation Error","content":{"application/json":{"schema":{"type":"object"}}}}}}}}} ``` ## DELETE /api/v1/token/{tokenId} > Revoke Token by its ID ```json {"openapi":"3.0.0","info":{"title":"GoodAccess Customer","version":"1.0.0"},"tags":[{"name":"Tokens"}],"servers":[{"url":"https://integration.goodaccess.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}},"paths":{"/api/v1/token/{tokenId}":{"delete":{"tags":["Tokens"],"summary":"Revoke Token by its ID","parameters":[{"in":"path","name":"tokenId","schema":{"type":"string"},"required":true,"description":"UUID of the token to revoke"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object"}}}}}}}}} ```