From f07b165ab7b0834eadbe05da81fc167dcc23d59d Mon Sep 17 00:00:00 2001 From: Valery Sizov Date: Mon, 12 Jan 2015 15:30:34 -0800 Subject: OAuth API documentation update --- doc/api/README.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'doc/api/README.md') diff --git a/doc/api/README.md b/doc/api/README.md index ffe250df3ff..8f919f5257d 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -51,6 +51,24 @@ curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" "http://example.com/api/v3/p The API uses JSON to serialize data. You don't need to specify `.json` at the end of API URL. +## Authentication with OAuth2 token + +Instead of the private_token you can transmit the OAuth2 access token as a header or as a parameter. + +### OAuth2 token (as a parameter) + +``` +curl https://localhost:3000/api/v3/user?access_token=OAUTH-TOKEN +``` + +### OAuth2 token (as a header) + +``` +curl -H "Authorization: Bearer OAUTH-TOKEN" https://localhost:3000/api/v3/user +``` + +Read more about [OAuth2 in GitLab](oauth2.md). + ## Status codes The API is designed to return different status codes according to context and action. In this way if a request results in an error the caller is able to get insight into what went wrong, e.g. status code `400 Bad Request` is returned if a required attribute is missing from the request. The following list gives an overview of how the API functions generally behave. -- cgit v1.2.1 From e6e337088bbb4736983119928b6b6b451bd3ef20 Mon Sep 17 00:00:00 2001 From: Ewan Edwards Date: Fri, 30 Jan 2015 10:24:45 -0800 Subject: Make all non-config/non-operational mentions of URL consistently capitalized. Make the plural version consistently "URLs". Fix an instance where the article "the" before URL was missing. --- doc/api/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/api/README.md') diff --git a/doc/api/README.md b/doc/api/README.md index 8f919f5257d..8cbba8598d5 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -97,7 +97,7 @@ Return values: ## Sudo -All API requests support performing an api call as if you were another user, if your private token is for an administration account. You need to pass `sudo` parameter by url or header with an id or username of the user you want to perform the operation as. If passed as header, the header name must be "SUDO" (capitals). +All API requests support performing an api call as if you were another user, if your private token is for an administration account. You need to pass `sudo` parameter by URL or header with an id or username of the user you want to perform the operation as. If passed as header, the header name must be "SUDO" (capitals). If a non administrative `private_token` is provided then an error message will be returned with status code 403: @@ -142,7 +142,7 @@ When listing resources you can pass the following parameters: - `page` (default: `1`) - page number - `per_page` (default: `20`, max: `100`) - number of items to list per page -[Link headers](http://www.w3.org/wiki/LinkHeader) are send back with each response. These have `rel` prev/next/first/last and contain the relevant URL. Please use these instead of generating your own urls. +[Link headers](http://www.w3.org/wiki/LinkHeader) are send back with each response. These have `rel` prev/next/first/last and contain the relevant URL. Please use these instead of generating your own URLs. ## id vs iid -- cgit v1.2.1 From 10e4e2110c388ac43f1ebf437b963f13a1882129 Mon Sep 17 00:00:00 2001 From: Sytse Sijbrandij Date: Wed, 18 Feb 2015 20:49:19 -0800 Subject: Improve the explanation and linking of the Oauth docs. --- doc/api/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'doc/api/README.md') diff --git a/doc/api/README.md b/doc/api/README.md index 8cbba8598d5..dec530d0b81 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -22,6 +22,7 @@ ## Clients Find API Clients for GitLab [on our website](https://about.gitlab.com/applications/#api-clients). +You can use [GitLab as an OAuth2 client](oauth2.md) to make API calls. ## Introduction @@ -67,7 +68,7 @@ curl https://localhost:3000/api/v3/user?access_token=OAUTH-TOKEN curl -H "Authorization: Bearer OAUTH-TOKEN" https://localhost:3000/api/v3/user ``` -Read more about [OAuth2 in GitLab](oauth2.md). +Read more about [GitLab as an OAuth2 client](oauth2.md). ## Status codes -- cgit v1.2.1