Applications API

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab Self-Managed, GitLab Dedicated

Use this API to manage instance-wide OAuth applications that:

You cannot use this API to manage group applications or individual user applications.

Prerequisites:

  • You must have administrator access to the instance.

Create an application

The availability of the granular_scopes attribute is controlled by a feature flag. For more information, see the history.

Creates an application.

Returns 200 if the request succeeds.

POST /applications

Supported attributes:

AttributeTypeRequiredDescription
namestringyesName of the application.
redirect_uristringyesRedirect URI of the application.
scopesstringyesScopes available to the application. Separate multiple scopes with a space.
confidentialbooleannoIf true, the application can securely store client credentials, such as the client secret. Non-confidential applications (such as native mobile apps and Single Page Apps) might expose client credentials. Defaults to true if unspecified.
granular_scopesarraynoGranular scopes to declare on the application, each pairing an access level with a list of permissions.
granular_scopes[].accessstringyesAccess level of the scope. One of user, instance, all_memberships, or selected_memberships.
granular_scopes[].permissionsarray of stringsyesNames of the permissions the scope grants, for example execute_mcp_tool or read_member_role.
granular_scopes[].group_idsarray of integersnoIDs of the groups the scope applies to. Used only when access is selected_memberships.
granular_scopes[].project_idsarray of integersnoIDs of the projects the scope applies to. Used only when access is selected_memberships.

Declaring granular scopes records which fine-grained permissions the application has, as a set of access levels and permissions. GitLab creates the application and stores this set together in one step. If GitLab rejects the set, it does not create the application.

Example request:

shell
curl --request POST \
    --header "PRIVATE-TOKEN: <your_access_token>" \
    --data "name=MyApplication&redirect_uri=http://redirect.uri&scopes=api read_user email" \
    --url "https://gitlab.example.com/api/v4/applications"

Example response:

json
{
    "id":1,
    "application_id": "5832fc6e14300a0d962240a8144466eef4ee93ef0d218477e55f11cf12fc3737",
    "application_name": "MyApplication",
    "secret": "ee1dd64b6adc89cf7e2c23099301ccc2c61b441064e9324d963c46902a85ec34",
    "callback_url": "http://redirect.uri",
    "confidential": true,
    "scopes": ["api", "read_user", "email"]
}

Example request with granular scopes:

shell
curl --request POST \
    --header "PRIVATE-TOKEN: <your_access_token>" \
    --header "Content-Type: application/json" \
    --data '{"name": "MyApplication", "redirect_uri": "http://redirect.uri", "scopes": "api", "granular_scopes": [{"access": "user", "permissions": ["execute_mcp_tool"]}, {"access": "selected_memberships", "permissions": ["read_member_role"], "group_ids": [5]}]}' \
    --url "https://gitlab.example.com/api/v4/applications"

The response adds these attributes:

AttributeTypeDescription
granular_scopesarrayGranular scopes stored on the application, each with access, permissions, group_id, and project_id.
granular_scopes[].group_idintegerID of the group when the scope targets a group, otherwise null.
granular_scopes[].project_idintegerID of the project when the scope targets a project, otherwise null.
warningsarray of stringsWarnings returned when no user scope grants execute_mcp_tool. Tokens for such an application cannot use the GitLab MCP server.

While an application has granular scopes, GitLab adds the granular scope to its scopes.

Example response:

json
{
    "id": 2,
    "application_id": "0a9c3b1f2e4d5c6b7a8f9e0d1c2b3a4f5e6d7c8b9a0f1e2d3c4b5a6f7e8d9c0b",
    "application_name": "MyApplication",
    "secret": "<application_secret>",
    "callback_url": "http://redirect.uri",
    "confidential": true,
    "scopes": ["api", "granular"],
    "granular_scopes": [
        { "access": "user", "permissions": ["execute_mcp_tool"], "project_id": null, "group_id": null },
        { "access": "selected_memberships", "permissions": ["read_member_role"], "project_id": null, "group_id": 5 }
    ]
}

List all applications

Lists all applications.

GET /applications

Example request:

shell
curl --request GET \
    --header "PRIVATE-TOKEN: <your_access_token>" \
    --url "https://gitlab.example.com/api/v4/applications"

Example response:

json
[
    {
        "id":1,
        "application_id": "5832fc6e14300a0d962240a8144466eef4ee93ef0d218477e55f11cf12fc3737",
        "application_name": "MyApplication",
        "callback_url": "http://redirect.uri",
        "confidential": true,
        "scopes": ["api", "read_user"]
    }
]

The secret value is not exposed by this API.

Delete an application

Deletes a specified application.

Returns 204 if the request succeeds.

DELETE /applications/:id

Supported attributes:

AttributeTypeRequiredDescription
idintegeryesThe ID of the application (not the application_id).

Example request:

shell
curl --request DELETE \
    --header "PRIVATE-TOKEN: <your_access_token>" \
    --url "https://gitlab.example.com/api/v4/applications/:id"

Renew an application secret

Renews the secret for a specified application. Returns 200 if the request succeeds.

POST /applications/:id/renew-secret

Supported attributes:

AttributeTypeRequiredDescription
idintegeryesThe ID of the application (not the application_id).

Example request:

shell
curl --request POST \
    --header "PRIVATE-TOKEN: <your_access_token>" \
    --url "https://gitlab.example.com/api/v4/applications/:id/renew-secret"

Example response:

json
{
    "id":1,
    "application_id": "5832fc6e14300a0d962240a8144466eef4ee93ef0d218477e55f11cf12fc3737",
    "application_name": "MyApplication",
    "secret": "ee1dd64b6adc89cf7e2c23099301ccc2c61b441064e9324d963c46902a85ec34",
    "callback_url": "http://redirect.uri",
    "confidential": true,
    "scopes": ["api", "read_user"]
}