Skip to main content
The REST API is now versioned. For more information, see "About API versioning."

REST API endpoints for enterprise users

Use the REST API to suspend, unsuspend, promote, and demote users on your enterprise.

About user administration

These endpoints are only available to authenticated site administrators. Normal users will receive a 403 response.

These endpoints only support authentication using a personal access token (classic). For more information, see "Managing your personal access tokens."

List public keys

Fine-grained access tokens for "List public keys"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "List public keys"

Headers
Name, Type, Description
accept string

Setting to application/vnd.github+json is recommended.

Query parameters
Name, Type, Description
per_page integer

The number of results per page (max 100). For more information, see "Using pagination in the REST API."

Default: 30

page integer

The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Default: 1

direction string

The direction to sort the results by.

Default: desc

Can be one of: asc, desc

sort string

Default: created

Can be one of: created, updated, accessed

since string

Only show public keys accessed after the given time.

HTTP response status codes for "List public keys"

Status codeDescription
200

OK

Code samples for "List public keys"

Request example

get/admin/keys
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ http(s)://HOSTNAME/api/v3/admin/keys

Response

Status: 200
[ { "key": "2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234", "id": 2, "url": "https://HOSTNAME/user/keys/2", "title": "ssh-rsa AAAAB3NzaC1yc2EAAA", "created_at": "2020-06-11T21:31:57Z", "verified": false, "read_only": false, "last_used": "2020-06-11T22:31:57Z", "user_id": 1, "repository_id": 2 }, { "key": "9Og8iYjAyymI9LvABpJerYrMxURPc8r+dB7TJyvv1234", "id": 3, "url": "https://HOSTNAME/user/keys/2", "title": "ssh-rsa AAAAB3NzaC1yc2EAAA", "created_at": "2020-06-11T21:31:57Z", "verified": false, "read_only": false, "last_used": "2020-06-11T22:31:57Z", "user_id": 1, "repository_id": 2 } ]

Delete a public key

Fine-grained access tokens for "Delete a public key"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "Delete a public key"

Headers
Name, Type, Description
accept string

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
key_ids string Required

The unique identifier of the key.

HTTP response status codes for "Delete a public key"

Status codeDescription
204

No Content

Code samples for "Delete a public key"

Request example

delete/admin/keys/{key_ids}
curl -L \ -X DELETE \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ http(s)://HOSTNAME/api/v3/admin/keys/KEY_IDS

Response

Status: 204

List personal access tokens

Lists personal access tokens for all users, including admin users.

Fine-grained access tokens for "List personal access tokens"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "List personal access tokens"

Headers
Name, Type, Description
accept string

Setting to application/vnd.github+json is recommended.

Query parameters
Name, Type, Description
per_page integer

The number of results per page (max 100). For more information, see "Using pagination in the REST API."

Default: 30

page integer

The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Default: 1

HTTP response status codes for "List personal access tokens"

Status codeDescription
200

OK

Code samples for "List personal access tokens"

Request example

get/admin/tokens
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ http(s)://HOSTNAME/api/v3/admin/tokens

Response

Status: 200
[ { "id": 2, "url": "https://enterprise.octocat.com/api/v3/authorizations/2", "app": { "name": "My personal access token", "url": "https://docs.github.com/enterprise/rest/enterprise-admin/users#list-personal-access-tokens", "client_id": "00000000000000000000" }, "token": "ghp_16C7e42F292c6912E7710c838347Ae178B4a", "hashed_token": "23cffb2fab1b0a62747863eba88cb9327e561f2f7a0c8661c0d9b83146cb8d45", "token_last_eight": "Ae178B4a", "note": "My personal access token", "note_url": null, "created_at": "2019-04-24T21:49:02Z", "updated_at": "2019-04-24T21:49:02Z", "scopes": [ "admin:business", "admin:gpg_key", "admin:org", "admin:org_hook", "admin:pre_receive_hook", "admin:public_key", "admin:repo_hook", "delete_repo", "gist", "notifications", "repo", "user", "write:discussion" ], "fingerprint": null } ]

Delete a personal access token

Deletes a personal access token. Returns a 403 - Forbidden status when a personal access token is in use. For example, if you access this endpoint with the same personal access token that you are trying to delete, you will receive this error.

Fine-grained access tokens for "Delete a personal access token"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "Delete a personal access token"

Headers
Name, Type, Description
accept string

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
token_id integer Required

The unique identifier of the token.

HTTP response status codes for "Delete a personal access token"

Status codeDescription
204

No Content

Code samples for "Delete a personal access token"

Request example

delete/admin/tokens/{token_id}
curl -L \ -X DELETE \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ http(s)://HOSTNAME/api/v3/admin/tokens/TOKEN_ID

Response

Status: 204

Create a user

If an external authentication mechanism is used, the login name should match the login name in the external system. If you are using LDAP authentication, you should also update the LDAP mapping for the user.

The login name will be normalized to only contain alphanumeric characters or single hyphens. For example, if you send "octo_cat" as the login, a user named "octo-cat" will be created.

If the login name or email address is already associated with an account, the server will return a 422 response.

Fine-grained access tokens for "Create a user"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "Create a user"

Headers
Name, Type, Description
accept string

Setting to application/vnd.github+json is recommended.

Body parameters
Name, Type, Description
login string Required

The user's username.

email string

Required for built-in authentication. The user's email address. This parameter can be omitted when using CAS, LDAP, or SAML. For more information, see "About authentication for your enterprise."

suspended boolean

Whether to set the user as suspended when the user is created.

Default: false

HTTP response status codes for "Create a user"

Status codeDescription
201

Created

Code samples for "Create a user"

Request example

post/admin/users
curl -L \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ http(s)://HOSTNAME/api/v3/admin/users \ -d '{"login":"monalisa","email":"octocat@github.com"}'

Response

Status: 201
{ "login": "octocat", "id": 1, "node_id": "MDQ6VXNlcjE=", "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "", "url": "https://HOSTNAME/users/octocat", "html_url": "https://github.com/octocat", "followers_url": "https://HOSTNAME/users/octocat/followers", "following_url": "https://HOSTNAME/users/octocat/following{/other_user}", "gists_url": "https://HOSTNAME/users/octocat/gists{/gist_id}", "starred_url": "https://HOSTNAME/users/octocat/starred{/owner}{/repo}", "subscriptions_url": "https://HOSTNAME/users/octocat/subscriptions", "organizations_url": "https://HOSTNAME/users/octocat/orgs", "repos_url": "https://HOSTNAME/users/octocat/repos", "events_url": "https://HOSTNAME/users/octocat/events{/privacy}", "received_events_url": "https://HOSTNAME/users/octocat/received_events", "type": "User", "site_admin": false }

Update the username for a user

Fine-grained access tokens for "Update the username for a user"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "Update the username for a user"

Headers
Name, Type, Description
accept string

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
username string Required

The handle for the GitHub user account.

Body parameters
Name, Type, Description
login string Required

The user's new username.

HTTP response status codes for "Update the username for a user"

Status codeDescription
202

Accepted

Code samples for "Update the username for a user"

Request example

patch/admin/users/{username}
curl -L \ -X PATCH \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ http(s)://HOSTNAME/api/v3/admin/users/USERNAME \ -d '{"login":"thenewmonalisa"}'

Response

Status: 202
{ "message": "Job queued to rename user. It may take a few minutes to complete.", "url": "https://HOSTNAME/user/1" }

Delete a user

Deleting a user will delete all their repositories, gists, applications, and personal settings. Suspending a user is often a better option.

You can delete any user account except your own.

Fine-grained access tokens for "Delete a user"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "Delete a user"

Headers
Name, Type, Description
accept string

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
username string Required

The handle for the GitHub user account.

HTTP response status codes for "Delete a user"

Status codeDescription
204

No Content

Code samples for "Delete a user"

Request example

delete/admin/users/{username}
curl -L \ -X DELETE \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ http(s)://HOSTNAME/api/v3/admin/users/USERNAME

Response

Status: 204

Create an impersonation OAuth token

Fine-grained access tokens for "Create an impersonation OAuth token"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "Create an impersonation OAuth token"

Headers
Name, Type, Description
accept string

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
username string Required

The handle for the GitHub user account.

Body parameters
Name, Type, Description
scopes array of strings Required

A list of scopes.

HTTP response status codes for "Create an impersonation OAuth token"

Status codeDescription
200

Response when getting an existing impersonation OAuth token

201

Response when creating a new impersonation OAuth token

Code samples for "Create an impersonation OAuth token"

Request examples

post/admin/users/{username}/authorizations
curl -L \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ http(s)://HOSTNAME/api/v3/admin/users/USERNAME/authorizations \ -d '{"scopes":["public_repo"]}'

Response when getting an existing impersonation OAuth token

Status: 200
{ "id": 1, "url": "https://HOSTNAME/authorizations/1", "scopes": [ "public_repo" ], "token": "ghu_16C7e42F292c6912E7710c838347Ae178B4a", "token_last_eight": "Ae178B4a", "hashed_token": "25f94a2a5c7fbaf499c665bc73d67c1c87e496da8985131633ee0a95819db2e8", "app": { "url": "http://my-github-app.com", "name": "my github app", "client_id": "abcde12345fghij67890" }, "note": "optional note", "note_url": "http://optional/note/url", "updated_at": "2011-09-06T20:39:23Z", "created_at": "2011-09-06T17:26:27Z", "expires_at": "2011-10-06T17:26:27Z", "fingerprint": "jklmnop12345678" }

Delete an impersonation OAuth token

Fine-grained access tokens for "Delete an impersonation OAuth token"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "Delete an impersonation OAuth token"

Headers
Name, Type, Description
accept string

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
username string Required

The handle for the GitHub user account.

HTTP response status codes for "Delete an impersonation OAuth token"

Status codeDescription
204

No Content

Code samples for "Delete an impersonation OAuth token"

Request example

delete/admin/users/{username}/authorizations
curl -L \ -X DELETE \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ http(s)://HOSTNAME/api/v3/admin/users/USERNAME/authorizations

Response

Status: 204

Promote a user to be a site administrator

Note that you'll need to set Content-Length to zero when calling out to this endpoint. For more information, see "HTTP method."

Fine-grained access tokens for "Promote a user to be a site administrator"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "Promote a user to be a site administrator"

Headers
Name, Type, Description
accept string

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
username string Required

The handle for the GitHub user account.

HTTP response status codes for "Promote a user to be a site administrator"

Status codeDescription
204

No Content

Code samples for "Promote a user to be a site administrator"

Request example

put/users/{username}/site_admin
curl -L \ -X PUT \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ http(s)://HOSTNAME/api/v3/users/USERNAME/site_admin

Response

Status: 204

Demote a site administrator

You can demote any user account except your own.

Fine-grained access tokens for "Demote a site administrator"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "Demote a site administrator"

Headers
Name, Type, Description
accept string

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
username string Required

The handle for the GitHub user account.

HTTP response status codes for "Demote a site administrator"

Status codeDescription
204

No Content

Code samples for "Demote a site administrator"

Request example

delete/users/{username}/site_admin
curl -L \ -X DELETE \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ http(s)://HOSTNAME/api/v3/users/USERNAME/site_admin

Response

Status: 204

Suspend a user

If your GitHub instance uses LDAP Sync with Active Directory LDAP servers, Active Directory LDAP-authenticated users cannot be suspended through this API. If you attempt to suspend an Active Directory LDAP-authenticated user through this API, it will return a 403 response.

You can suspend any user account except your own.

Note that, if you choose not to pass any parameters, you'll need to set Content-Length to zero when calling out to this endpoint. For more information, see "HTTP method."

Fine-grained access tokens for "Suspend a user"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "Suspend a user"

Headers
Name, Type, Description
accept string

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
username string Required

The handle for the GitHub user account.

Body parameters
Name, Type, Description
reason string

The reason the user is being suspended. This message will be logged in the audit log. If you don't provide a reason, it will default to "Suspended via API by SITE_ADMINISTRATOR", where SITE_ADMINISTRATOR is the person who performed the action.

HTTP response status codes for "Suspend a user"

Status codeDescription
204

No Content

Code samples for "Suspend a user"

Request example

put/users/{username}/suspended
curl -L \ -X PUT \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ http(s)://HOSTNAME/api/v3/users/USERNAME/suspended \ -d '{"reason":"Suspended during leave of absence."}'

Response

Status: 204

Unsuspend a user

If your GitHub instance uses LDAP Sync with Active Directory LDAP servers, this API is disabled and will return a 403 response. Active Directory LDAP-authenticated users cannot be unsuspended using the API.

Fine-grained access tokens for "Unsuspend a user"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "Unsuspend a user"

Headers
Name, Type, Description
accept string

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
username string Required

The handle for the GitHub user account.

Body parameters
Name, Type, Description
reason string

The reason the user is being unsuspended. This message will be logged in the audit log. If you don't provide a reason, it will default to "Unsuspended via API by SITE_ADMINISTRATOR", where SITE_ADMINISTRATOR is the person who performed the action.

HTTP response status codes for "Unsuspend a user"

Status codeDescription
204

No Content

Code samples for "Unsuspend a user"

Request example

delete/users/{username}/suspended
curl -L \ -X DELETE \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ http(s)://HOSTNAME/api/v3/users/USERNAME/suspended \ -d '{"reason":"Unsuspended after leave of absence."}'

Response

Status: 204