The GitHub Users API (part of the REST API) lets applications read and, for the authenticated account, manage user-related data on GitHub. It can fetch public profiles for any user or the authenticated users private profile details, list a users public repositories and organizations, and view activity like followers and following.
openapi: 3.0.3
info:
version: 1.1.4
title: GitHub User API
description: |-
Use the REST API to get public and private information about authenticated
users.
license:
name: MIT
url: https://spdx.org/licenses/MIT
termsOfService: https://docs.github.com/articles/github-terms-of-service
contact:
name: Support
url: https://support.github.com/contact?tags=dotcom-rest-api
x-github-plan: ghes
x-github-release: 3.9
tags:
- name: Accept
- name: Access
- name: Accessible
- name: Account
- name: Accounts
- name: Add
- name: Address
- name: Addresses
- name: Administrator
- name: Another
- name: Applications
- name: Archive
- name: Assigned
- name: Authenticated
- name: Branches
- name: Checks
- name: Conflicting
- name: Contextual
- name: Create
- name: Decline
- name: Delete
- name: Demote
- name: Docker
- name: Download
- name: During
- name: Email
- name: Emails
- name: Events
- name: Follow
- name: Followed
- name: Followers
- name: Follows
- name: Get
- name: Gists
- name: Gpg
- name: Impersonation
- name: Information
- name: Installations
- name: Invitation
- name: Invitations
- name: Issues
- name: Keys
- name: Ldap
- name: Lists
- name: Mapping
- name: Memberships
- name: Migrations
- name: Oauth
- name: Organizations
- name: Owned
- name: Package
- name: Packages
- name: People
- name: Person
- name: Projects
- name: Promote
- name: Protected
- name: Public
- name: Received
- name: Remove
- name: Repositories
- name: Restore
- name: Restrictions
- name: Search
- name: Sets
- name: Signing
- name: Sites
- name: Social
- name: Ssh
- name: Star
- name: Starred
- name: Start
- name: Statistics
- name: Suspend
- name: Sync
- name: Teams
- name: Tokens
- name: Unfollow
- name: Unstar
- name: Unsuspend
- name: Update
- name: Username
- name: Users
- name: Versions
- name: Watched
servers:
- url: '{protocol}://{hostname}'
variables:
hostname:
description: Self-hosted Enterprise Server hostname
default: api.github.com
protocol:
description: Self-hosted Enterprise Server protocol
default: https
externalDocs:
description: GitHub Enterprise Developer Docs
url: https://docs.github.com/[email protected]/rest/
paths:
/admin/ldap/users/{username}/mapping:
patch:
summary: GitHub Update Ldap Mapping for User
description: >-
Updates the LDAP mapping for an authenticated user by modifying the
distinguished name (DN) that maps a specific GitHub Enterprise Server
user account to an LDAP directory entry. This endpoint allows
administrators to change or correct the LDAP authentication mapping for
a user, which is useful when LDAP directory structure changes or when a
user's DN needs to be updated without recreating the GitHub account. The
operation requires admin privileges and updates the synchronization
between the GitHub user and their corresponding LDAP identity, ensuring
continued authentication and authorization through the LDAP directory.
operationId: updateLdapMappingForUser
tags:
- Ldap
- Mapping
- Update
- Users
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/enterprise-admin/ldap#update-ldap-mapping-for-a-user
parameters:
- $ref: '#/components/parameters/username'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/ldap-mapping-user'
examples:
default:
$ref: '#/components/examples/ldap-mapping-user'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
ldap_dn:
type: string
description: >-
The [distinguished
name](https://www.ldap.com/ldap-dns-and-rdns) (DN) of the
LDAP entry to map to a team.
required:
- ldap_dn
examples:
default:
value:
ldap_dn: uid=asdf,ou=users,dc=github,dc=com
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: enterprise-admin
subcategory: ldap
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/admin/ldap/users/{username}/sync:
post:
summary: GitHub Sync Ldap Mapping for User
description: >-
Note that this API call does not automatically initiate an LDAP sync.
Rather, if a `201` is returned, the sync job is queued successfully, and
is performed when the instance is ready.
operationId: syncLdapMappingForUser
tags:
- Ldap
- Mapping
- Sync
- Users
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/enterprise-admin/ldap#sync-ldap-mapping-for-a-user
parameters:
- $ref: '#/components/parameters/username'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'201':
description: Response
content:
application/json:
schema:
type: object
properties:
status:
type: string
examples:
default:
value:
status: queued
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: enterprise-admin
subcategory: ldap
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/admin/users:
post:
summary: GitHub Create User
description: >-
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](https://docs.github.com/[email protected]/rest/enterprise-admin/ldap#update-ldap-mapping-for-a-user)
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.
operationId: createUser
tags:
- Create
- Users
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/enterprise-admin/users#create-a-user
responses:
'201':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/simple-user'
examples:
default:
$ref: '#/components/examples/simple-user'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
login:
type: string
description: The user's username.
email:
type: string
description: >-
**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](https://docs.github.com/[email protected]/admin/identity-and-access-management/managing-iam-for-your-enterprise/about-authentication-for-your-enterprise)."
suspended:
type: boolean
description: >-
Whether to set the user as suspended when the user is
created.
default: false
required:
- login
examples:
default:
value:
login: monalisa
email: [email protected]
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: enterprise-admin
subcategory: users
parameters:
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/admin/users/{username}:
patch:
summary: GitHub Update the Username for User
description: >-
The PATCH operation on the /admin/users/{username} endpoint allows
administrators to update the username for a specific GitHub user
account. This API call requires admin privileges and targets a specific
user by their current username in the URL path. The operation modifies
the user's login identifier while preserving their account history,
repositories, and associated data. This is typically used for account
maintenance purposes such as correcting usernames, handling name
changes, or resolving conflicts, and requires appropriate authentication
and authorization to prevent unauthorized modifications to user
accounts.
operationId: updateTheUsernameForUser
tags:
- Update
- Username
- Users
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/enterprise-admin/users#update-the-username-for-a-user
parameters:
- $ref: '#/components/parameters/username'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'202':
description: Response
content:
application/json:
schema:
type: object
properties:
message:
type: string
url:
type: string
examples:
default:
value:
message: >-
Job queued to rename user. It may take a few minutes to
complete.
url: https://api.github.com/user/1
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
login:
type: string
description: The user's new username.
required:
- login
examples:
default:
value:
login: thenewmonalisa
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: enterprise-admin
subcategory: users
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
summary: GitHub Delete User
description: >-
Deleting a user will delete all their repositories, gists, applications,
and personal settings. [Suspending a
user](https://docs.github.com/[email protected]/rest/enterprise-admin/users#suspend-a-user)
is often a better option.
You can delete any user account except your own.
operationId: deleteUser
tags:
- Delete
- Users
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/enterprise-admin/users#delete-a-user
parameters:
- $ref: '#/components/parameters/username'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'204':
description: Response
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: enterprise-admin
subcategory: users
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/admin/users/{username}/authorizations:
post:
summary: GitHub Create an Impersonation Oauth Token
description: >-
The GitHub User API endpoint `/admin/users/{username}/authorizations`
with the POST method allows site administrators to create an
impersonation OAuth token for a specific user. This endpoint is part of
GitHub Enterprise Server's administrative capabilities and enables
admins to generate access tokens on behalf of any user account without
requiring their password or existing credentials. The impersonation
token can be scoped with specific permissions and is useful for
troubleshooting user issues, performing administrative actions in the
context of a particular user, or testing user-specific functionality.
This is a privileged operation that requires administrator
authentication and should be used carefully as it grants access to
another user's resources and data. The generated token behaves like a
standard OAuth token and can be used to make authenticated API requests
as if they were coming from the impersonated user.
operationId: createAnImpersonationOauthToken
tags:
- Create
- Impersonation
- Oauth
- Tokens
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/enterprise-admin/users#create-an-impersonation-oauth-token
parameters:
- $ref: '#/components/parameters/username'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'200':
description: Response when getting an existing impersonation OAuth token
content:
application/json:
schema:
$ref: '#/components/schemas/authorization'
examples:
default:
$ref: '#/components/examples/authorization'
'201':
description: Response when creating a new impersonation OAuth token
content:
application/json:
schema:
$ref: '#/components/schemas/authorization'
examples:
default:
$ref: '#/components/examples/authorization'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
scopes:
type: array
description: >-
A list of
[scopes](https://docs.github.com/[email protected]/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/).
items:
type: string
required:
- scopes
examples:
default:
value:
scopes:
- public_repo
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: enterprise-admin
subcategory: users
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
summary: GitHub Delete an Impersonation Oauth Token
description: >-
This API operation allows GitHub administrators to delete an OAuth token
that has been created for impersonating a specific user. By sending a
DELETE request to the endpoint with the target username, admins can
revoke impersonation tokens that were previously generated for
administrative purposes, such as debugging or user support. This helps
maintain security by ensuring that impersonation access can be promptly
removed when no longer needed, preventing unauthorized or prolonged
access to user accounts through administrative privileges.
operationId: deleteAnImpersonationOauthToken
tags:
- Delete
- Impersonation
- Oauth
- Tokens
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/enterprise-admin/users#delete-an-impersonation-oauth-token
parameters:
- $ref: '#/components/parameters/username'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'204':
description: Response
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: enterprise-admin
subcategory: users
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/enterprise/stats/users:
get:
summary: GitHub Get Users Statistics
description: >-
The GitHub User API endpoint `/enterprise/stats/users` using the GET
method retrieves statistical information about users within a GitHub
Enterprise instance. This endpoint provides aggregate data and metrics
related to user accounts, which may include information such as total
user counts, active users, user growth trends, and other relevant
user-related statistics that help administrators monitor and analyze
user engagement and activity across their enterprise organization.
operationId: getUsersStatistics
tags:
- Get
- Statistics
- Users
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/enterprise-admin/admin-stats#get-users-statistics
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/enterprise-user-overview'
examples:
default:
value:
total_users: 100
admin_users: 3
suspended_users: 1
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: enterprise-admin
subcategory: admin-stats
parameters:
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/branches/{branch}/protection/restrictions/users:
get:
summary: GitHub Get Users with Access to the Protected Branch
description: >-
Protected branches are available in public repositories with GitHub Free
and GitHub Free for organizations, and in public and private
repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and
GitHub Enterprise Server. For more information, see [GitHub's
products](https://docs.github.com/[email protected]/github/getting-started-with-github/githubs-products)
in the GitHub Help documentation.
Lists the people who have push access to this branch.
tags:
- Access
- Branches
- Get
- Protected
- Users
operationId: getUsersWithAccessToTheProtectedBranch
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/branches/branch-protection#get-users-with-access-to-the-protected-branch
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/branch'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/simple-user'
examples:
default:
$ref: '#/components/examples/simple-user-items'
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: branches
subcategory: branch-protection
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
summary: GitHub Add User Access Restrictions
description: >-
Protected branches are available in public repositories with GitHub Free
and GitHub Free for organizations, and in public and private
repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and
GitHub Enterprise Server. For more information, see [GitHub's
products](https://docs.github.com/[email protected]/github/getting-started-with-github/githubs-products)
in the GitHub Help documentation.
Grants the specified people push access for this branch.
| Type |
Description |
| - | -- |
| `array` | Usernames for people who can have push access. **Note**: The
list of users, apps, and teams in total is limited to 100 items. |
tags:
- Access
- Add
- Restrictions
- Users
operationId: addUserAccessRestrictions
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/branches/branch-protection#add-user-access-restrictions
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/branch'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
requestBody:
required: false
content:
application/json:
schema:
oneOf:
- type: object
properties:
users:
type: array
description: The username for users
items:
type: string
required:
- users
example:
users:
- mona
- type: array
items:
type: string
examples:
default:
summary: Example adding a user in a branch protection rule
value:
users:
- octocat
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/simple-user'
examples:
default:
$ref: '#/components/examples/simple-user-items'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
requestBodyParameterName: users
category: branches
subcategory: branch-protection
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
summary: GitHub Set User Access Restrictions
description: >-
Protected branches are available in public repositories with GitHub Free
and GitHub Free for organizations, and in public and private
repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and
GitHub Enterprise Server. For more information, see [GitHub's
products](https://docs.github.com/[email protected]/github/getting-started-with-github/githubs-products)
in the GitHub Help documentation.
Replaces the list of people that have push access to this branch. This
removes all people that previously had push access and grants push
access to the new list of people.
| Type |
Description |
| - | -- |
| `array` | Usernames for people who can have push access. **Note**: The
list of users, apps, and teams in total is limited to 100 items. |
tags:
- Access
- Restrictions
- Sets
- Users
operationId: setUserAccessRestrictions
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/branches/branch-protection#set-user-access-restrictions
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/branch'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: header
name: X-GitHub-Api-Version
schema:
type: string
default: '2022-11-28'
example: example_value
- in: header
name: Accept
schema:
type: string
default: application/vnd.github+json
example: example_value
requestBody:
required: false
content:
application/json:
schema:
oneOf:
- type: object
properties:
users:
type: array
description: The username for users
items:
type: string
required:
- users
example:
users:
- mona
- type: array
items:
type: string
examples:
default:
summary: Example replacing a user in a branch protection rule
value:
users:
- octocat
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/simple-user'
examples:
default:
$ref: '#/components/examples/simple-user-items'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
requestBodyParameterName: users
category: branches
subcategory: branch-protection
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
summary: GitHub Remove User Access Restrictions
description: >-
Protected branches are available in public repositories with GitHub Free
and GitHub Free for organizations, and in public and private
repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and
GitHub Enterprise Server. For more information, see [GitHub's
products](https://docs.github.com/[email protected]/github/getting-started-with-github/githubs-products)
in the GitHub Help documentation.
Removes the ability of a user to push to this branch.
| Type |
Description |
| - |
|
| `array` | Usernames of the people who should no longer have push
access. **Note**: The list of users, apps, and teams in total is limited
to 100 items. |
tags:
- Access
- Remove
- Restrictions
- Users
operationId: removeUserAccessRestrictions
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/branches/branch-protection#remove-user-access-restrictions
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/branch'
- in: header
name: Authorization
schema:
type: string
example: example_value
- in: head
# --- truncated at 32 KB (609 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/openapi/github-users-api-openapi.yml