Groups

End of Sale Announcement

Effective May 1, 2026, Okta will no longer sell or renew Advanced Server Access. Existing customers must migrate to Okta Privileged Access within one year of their next scheduled renewal date to maintain service. Read the FAQ | Learn about Okta Privileged Access

List all Groups for a Team
Admin roles:
  • access_user
  • access_admin
  • reporting_user

Lists all Groups for your Team

SecuritybearerAuth
Request
path Parameters
team_name
required
string

The name of your Team

query Parameters
offset
string

The UUID of an object used as an offset for pagination

count
integer <int32>

Controls the number of objects listed per page

descending
boolean

If 'true', the most recent results are listed first

prev
boolean

Controls the direction of paging

contains
string

If defined, results only include Groups that use the specified value in their name

include_deleted
boolean

If 'true', results also include previously deleted Groups

only_include_deleted
boolean

If 'true', results only include previously deleted Groups

disconnected_mode_on_only
boolean

If 'true', results only include Groups that have enabled disconnected mode

id
string

If defined, results only include Groups with the specified IDs

ignore
string

If defined, results don't include Groups with the specified names. This is case sensitive.

Responses
200

OK

get/v1/teams/{team_name}/groups
Request samples 
Response samples 
application/json
{
  • "list": [
    • {
      },
    • {
      }
    ]
}
Create a Group
Admin roles: 
  • access_admin
Creates a Group for your Team. Groups allow you to assign RBAC roles to users and manage user access to Projects.


SecuritybearerAuth 
Request 
path Parameters
team_name
required
string
The name of your Team


 
Request Body schema: application/json
required
federated_from_team
string or null  [ 1 .. 1024 ] characters 
(Optional) The name of the Team from which to federate the Group


 
name
required
string  [ 1 .. 255 ] characters 
The name of the Group


 
roles
required
Array of strings
The roles assigned to the Group. Possible values: access_user, access_admin, and reporting_user.


 
Responses 
201
Created


post/v1/teams/{team_name}/groups
Request samples 
application/json
{
  • "deleted_at": null,
  • "federated_from_team": null,
  • "federation_approved_at": null,
  • "id": "",
  • "name": "compsons",
  • "roles": [
    • "access_user",
    • "reporting_user",
    • "access_admin"
    ]
}
Response samples 
application/json
{
  • "deleted_at": "0001-01-01T00:00:00Z",
  • "federated_from_team": null,
  • "federation_approved_at": null,
  • "id": "7f9901bd-7ca8-4653-af8e-ab5c2151236c",
  • "name": "compsons",
  • "roles": [
    • "access_user",
    • "reporting_user",
    • "access_admin"
    ]
}
Retrieve a Group
Admin roles: 
  • access_user
  • access_admin
  • reporting_user
Retrieves a specified Group


SecuritybearerAuth 
Request 
path Parameters
team_name
required
string
The name of your Team


 
group_name
required
string
The ASA Group name


 
Responses 
200
OK


get/v1/teams/{team_name}/groups/{group_name}
Request samples 
Response samples 
application/json
{
  • "deleted_at": "0001-01-01T00:00:00Z",
  • "federated_from_team": null,
  • "federation_approved_at": null,
  • "id": "7f9901bd-7ca8-4653-af8e-ab5c2151236c",
  • "name": "compsons",
  • "roles": [
    • "access_user",
    • "reporting_user",
    • "access_admin"
    ]
}
Update a Group
Admin roles: 
  • access_admin
Updates the access privileges of the specified Group


SecuritybearerAuth 
Request 
path Parameters
team_name
required
string
The name of your Team


 
group_name
required
string
The ASA Group name


 
Request Body schema: application/json
required
roles
required
Array of strings
The roles assigned to the Group. Possible values: access_user, access_admin and reporting_user.


 
Responses 
204
No Content


put/v1/teams/{team_name}/groups/{group_name}
Request samples 
application/json
{
  • "roles": [
    • "access_user",
    • "reporting_user",
    • "access_admin"
    ]
}
Remove a Group from a Team
Admin roles: 
  • access_admin
Removes a Group from your Team. This also removes the Group from any associated Projects.


SecuritybearerAuth 
Request 
path Parameters
team_name
required
string
The name of your Team


 
group_name
required
string
The ASA Group name


 
Responses 
204
No Content


delete/v1/teams/{team_name}/groups/{group_name}
Request samples 
Update a Group
Admin roles: 
  • access_admin
Updates the access privileges of the specified Group


SecuritybearerAuth 
Request 
path Parameters
team_name
required
string
The name of your Team


 
group_name
required
string
The ASA Group name


 
Request Body schema: application/json
required
roles
required
Array of strings
The roles assigned to the Group. Possible values: access_user, access_admin and reporting_user.


 
Responses 
204
No Content


get/v1/teams/{team_name}/groups/{group_name}/disconnected_mode
Request samples 
application/json
{
  • "roles": [
    • "access_user",
    • "reporting_user",
    • "access_admin"
    ]
}
List all Users for a Group
Admin roles: 
  • access_user
  • access_admin
  • reporting_user
Lists all Users in a specified Group


SecuritybearerAuth 
Request 
path Parameters
team_name
required
string
The name of your Team


 
group_name
required
string
The ASA Group name


 
query Parameters
offset
string
The UUID of an object used as an offset for pagination


 
count
integer <int32> 
Controls the number of objects listed per page


 
descending
boolean
If 'true', the most recent results are listed first


 
prev
boolean
Controls the direction of paging


 
starts_with
string
Includes ASA Users with a name that begins with the provided value


 
status
string
Includes ASA Users with the specified statuses. Valid statuses: 'ACTIVE', 'DISABLED', and 'DELETED'.


 
contains
string
Includes ASA Users with name that contains the value


 
user_type
string
Includes ASA Users of the specified type. Valid types: 'human' and 'service'.


 
Responses 
200
OK


get/v1/teams/{team_name}/groups/{group_name}/users
Request samples 
Response samples 
application/json
{
  • "list": [
    • {
      }
    ]
}
Add a User to a Group
Admin roles: 
  • access_admin
Adds a User to a Group


SecuritybearerAuth 
Request 
path Parameters
team_name
required
string
The name of your Team


 
group_name
required
string
The ASA Group name


 
Request Body schema: application/json
required
object or null
The details of the User


 
email
string or null <regex>   [ 1 .. 255 ] characters ^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9]...
 
first_name
string or null  [ 1 .. 255 ] characters 
 
full_name
string or null  [ 1 .. 512 ] characters 
 
last_name
string or null  [ 1 .. 255 ] characters 
 
name
required
string  [ 1 .. 255 ] characters 
The username of the User


 
status
required
string
The status of the User: ACTIVE, DISABLED, or DELETED. Users can't disable or delete their own account.


 
Responses 
204
No Content


post/v1/teams/{team_name}/groups/{group_name}/users
Request samples 
application/json
{
  • "deleted_at": null,
  • "details": {
    • "email": "jason.compson@example.com",
    • "first_name": "Jason",
    • "full_name": "Jason Compson IV",
    • "last_name": "Compson"
    },
  • "id": "6768ef2e-9a17-42ce-bf9a-a3a7242bd159",
  • "name": "Jason.Compson.IV",
  • "status": "ACTIVE",
  • "team_name": "william-faulkner",
  • "user_type": "human"
}
Remove a User from a Group
Admin roles: 
  • access_admin
Removes a User from a Group


SecuritybearerAuth 
Request 
path Parameters
team_name
required
string
The name of your Team


 
group_name
required
string
The ASA Group name


 
user_name
required
string
The relevant username


 
Responses 
204
No Content


delete/v1/teams/{team_name}/groups/{group_name}/users/{user_name}
Request samples