diff options
author | Timothy Andrew <mail@timothyandrew.net> | 2016-04-28 17:18:49 +0530 |
---|---|---|
committer | Timothy Andrew <mail@timothyandrew.net> | 2016-04-28 22:28:36 +0530 |
commit | 2768e99ac386598480a7ac5490deee644125dfa1 (patch) | |
tree | d66be96037ccd046d7360b383c2f3903303d2077 /doc/api/README.md | |
parent | bafbf22c6ab613d25287d7119d7e30770c531fdb (diff) | |
download | gitlab-ce-2768e99ac386598480a7ac5490deee644125dfa1.tar.gz |
Add documentation for personal access tokens.
Diffstat (limited to 'doc/api/README.md')
-rw-r--r-- | doc/api/README.md | 61 |
1 files changed, 37 insertions, 24 deletions
diff --git a/doc/api/README.md b/doc/api/README.md index ff039f1886f..0e9dc7acfed 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -37,13 +37,11 @@ following locations: ## Authentication -All API requests require authentication. You need to pass a `private_token` -parameter via query string or header. If passed as a header, the header name -must be `PRIVATE-TOKEN` (uppercase and with a dash instead of an underscore). -You can find or reset your private token in your account page (`/profile/account`). +All API requests require authentication via a token. There are three types of tokens +available: private tokens, OAuth 2 tokens, and personal access tokens. -If `private_token` is invalid or omitted, then an error message will be -returned with status code `401`: +If a token is invalid or omitted, an error message will be returned with +status code `401`: ```json { @@ -51,42 +49,56 @@ returned with status code `401`: } ``` -API requests should be prefixed with `api` and the API version. The API version -is defined in [`lib/api.rb`][lib-api-url]. +### Private Tokens -Example of a valid API request: +You need to pass a `private_token` parameter via query string or header. If passed as a +header, the header name must be `PRIVATE-TOKEN` (uppercase and with a dash instead of +an underscore). You can find or reset your private token in your account page +(`/profile/account`). -```shell -GET https://gitlab.example.com/api/v3/projects?private_token=9koXpg98eAheJpvBs5tK -``` +### OAuth 2 Tokens -Example of a valid API request using cURL and authentication via header: +You can use an OAuth 2 token to authenticate with the API by passing it either in the +`access_token` parameter or in the `Authorization` header. + +Example of using the OAuth2 token in the header: ```shell -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects" +curl -H "Authorization: Bearer OAUTH-TOKEN" https://gitlab.example.com/api/v3/projects ``` -The API uses JSON to serialize data. You don't need to specify `.json` at the -end of an API URL. +Read more about [GitLab as an OAuth2 client](oauth2.md). + +### Personal Access Tokens -## Authentication with OAuth2 token +> **Note:** This feature was [introduced][ce-3749] in GitLab 8.8 -Instead of the `private_token` you can transmit the OAuth2 access token as a -header or as a parameter. +You can create as many personal access tokens as you like from your GitLab +profile (`/profile/personal_access_tokens`); perhaps one for each application +that needs access to the GitLab API. -Example of OAuth2 token as a parameter: +Once you have your token, pass it to the API using either the `personal_access_token` +parameter or the `PERSONAL-ACCESS-TOKEN` header. + +## Basic Usage + +API requests should be prefixed with `api` and the API version. The API version +is defined in [`lib/api.rb`][lib-api-url]. + +Example of a valid API request: ```shell -curl https://gitlab.example.com/api/v3/user?access_token=OAUTH-TOKEN +GET https://gitlab.example.com/api/v3/projects?private_token=9koXpg98eAheJpvBs5tK ``` -Example of OAuth2 token as a header: +Example of a valid API request using cURL and authentication via header: ```shell -curl -H "Authorization: Bearer OAUTH-TOKEN" https://example.com/api/v3/user +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects" ``` -Read more about [GitLab as an OAuth2 client](oauth2.md). +The API uses JSON to serialize data. You don't need to specify `.json` at the +end of an API URL. ## Status codes @@ -323,3 +335,4 @@ programming languages. Visit the [GitLab website] for a complete list. [GitLab website]: https://about.gitlab.com/applications/#api-clients "Clients using the GitLab API" [lib-api-url]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/api/api.rb +[ce-3749]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3749 |