取得存取權杖與權限

本指南將說明如何使用授權視窗從 Instagram 用戶取得短期 Instagram 用戶存取權杖和權限。

步驟 1：取得授權

授權視窗允許應用程式用戶授予您的應用程式權限和短期 Instagram 用戶存取權杖。用戶登入並選擇可允許應用程式存取哪些資料後，我們會將用戶重新導向至您的應用程式並加入授權碼，然後您可將代碼換成短期存取權杖。

若要開始此程序，請取得授權視窗並將其呈現給該用戶：

https://api.instagram.com/oauth/authorize
  ?client_id={instagram-app-id}
  &redirect_uri={redirect-uri}
  &scope={scope}
  &response_type=code
  &state={state}        //Optional

查詢字串參數

除了 state 之外，其餘所有參數皆為必要。

參數	範例值	說明
`client_id` 必要數值字串	`990602627938098`	顯示在應用程式主控板 > 產品 > Instagram > 基本顯示的 Instagram 應用程式編號。
`redirect_uri` 必要字串	`https://socialsizzle.herokuapp.com/auth/`	用戶允許或拒絕權限要求後，我們用來將他們重新導向的 URI。請確定此 URI 與您的有效 oAuth URI 清單中的其中一個基本 URI 完全相符。請注意，應用程式主控板可能在 URI 行尾加上斜線，因此建議您檢查清單進行驗證。
`response_type` 必要字串	`code`	將此值設為 `code`。
`scope` 必要逗號分隔或空格分隔清單	`user_profile,user_media`	向應用程式用戶要求的權限逗號分隔清單或網址編碼空格分隔清單。`user_profile` 為必要項目。
`state` 字串	`1`	選用值，表示伺服器的專屬狀態。例如，您可以用此來防範 CSRF 問題。我們在將用戶重新導向給您時，會包含此參數和值。

授權視窗網址範例

https://api.instagram.com/oauth/authorize
  ?client_id=990602627938098
  &redirect_uri=https://socialsizzle.herokuapp.com/auth/
  &scope=user_profile,user_media
  &response_type=code

成功授權

如果授權成功，我們會將用戶重新導向至您的 redirect_uri，並透過 code 查詢字串參數傳給您一個授權碼。請擷取該代碼，如此您的應用程式可以將其換成短期 Instagram 用戶存取權杖。

授權碼有效時間為 1 小時，且只能使用一次。

成功授權重新導向範例

https://socialsizzle.herokuapp.com/auth/?code=AQBx-hBsH3...#_

請注意，#_ 將附加到重新導向 URI 的結尾，但它不是代碼本身的一部分，因此請先將其刪除。

取消授權

如果用戶取消授權流程，我們會將用戶重新導向至您的 redirect_uri，並附加下列錯誤參數。在這些情況下，您必須負責完善處理不足之處，並向用戶顯示適當的訊息。

參數	值
`error`	`access_denied`
`error_reason`	`user_denied`
`error_description`	`The+user+denied+your+request`

取消授權重新導向範例

https://socialsizzle.herokuapp.com/auth/?error=access_denied
  &error_reason=user_denied
  &error_description=The+user+denied+your+request

步驟 2：將代碼換成權杖

一旦收到代碼之後，請將 POST 要求傳送至以下端點，以便將其換成短期存取權杖：

POST https://api.instagram.com/oauth/access_token

內文參數

請在 POST 要求內文中包含以下參數。

參數	範例值	說明
`client_id` 必要數值字串	`990602627938098`	顯示在應用程式主控板 > 產品 > Instagram > 基本顯示的 Instagram 應用程式編號。
`client_secret` 必要字串	`a1b2C3D4`	顯示在應用程式主控板 > 產品 > Instagram > 基本顯示的 Instagram 應用程式密鑰。
`code` 必要字串	`AQBx-hBsH3...`	將用戶重新導向至您的 `redirect_uri` 時，我們透過 `code` 參數傳給您的授權碼。
`grant_type` 必要字串	`authorization_code`	將此值設為 `authorization_code`。
`redirect_uri` 必要字串	`https://socialsizzle. heroku.com/auth/`	當您將用戶導向至授權視窗時，您傳給我們的重新導向 URI。這必須是相同的 URI，否則我們將拒絕要求。

要求範例

curl -X POST \
  https://api.instagram.com/oauth/access_token \
  -F client_id=990602627938098 \
  -F client_secret=eb8c7... \
  -F grant_type=authorization_code \
  -F redirect_uri=https://socialsizzle.herokuapp.com/auth/ \
  -F code=AQBx-hBsH3...

成功回應範例

若成功，此 API 將傳回 JSON 承載，且內含應用程式用戶的短期存取權杖和用戶編號。

{
  "access_token": "IGQVJ...",
  "user_id": 17841405793187218
}

擷取 access_token 值。這是用戶的短期 Instagram 用戶存取權杖，您的應用程式可以使用它來存取 Instagram 基本顯示 API 端點。

拒絕回應範例

如果該要求在某方面格式不正確，API 將傳回錯誤。

{
  "error_type": "OAuthException",
  "code": 400,
  "error_message": "Matching code was not found or was already used"
}