{"_id":"591cd2057b75113b005b09e3","project":"55a6e72e8cc73e0d00096635","user":"55a6caa022cfa321008e01d6","__v":1,"parentDoc":null,"category":{"_id":"5605f2bba4574a0d00811365","__v":26,"pages":["5608e4d6c5cff70d007d00d5","5608e4e7c5cff70d007d00d8","5608e4fbc5cff70d007d00da","5608e5096d8c440d000c79f3","5608e5156d8c440d000c79f6","5608e52331beb60d001b6558","5608e8248aedf50d0004cf98","5608e87e8aedf50d0004cf9b","5609bf4f9f85a70d00908530","562822dd5cfea90d00ddc5d7","562831c40653060d00a2f750","563d2732260dde0d00c5eab1","5660d2bee163310d006b19c1","567bb35b93919f0d00c97b1c","567bba643241c20d00b730de","567bbc14b56bac0d0019d933","567bc0473241c20d00b730e5","568b6bd8fe6fcc0d006dc8f7","56a427125fb2530d00421b67","56a42a5194ec0a0d00b3a012","56a42aaa545bc50d000e3ada","56ddff97bea78e20003a778f","56de00ab26744429006648ba","56de12a33168720e00c11b02","56e37f388b32a10e00f79755","56e73362e622c90e00dc55b3"],"project":"55a6e72e8cc73e0d00096635","version":"55a6e72f8cc73e0d00096638","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-09-26T01:19:55.795Z","from_sync":false,"order":2,"slug":"installation-and-launch","title":"Installation and Launch"},"version":{"_id":"55a6e72f8cc73e0d00096638","project":"55a6e72e8cc73e0d00096635","hasReference":false,"__v":29,"hasDoc":true,"createdAt":"2015-07-15T23:05:19.125Z","releaseDate":"2015-07-15T23:05:19.125Z","categories":["55a6e7308cc73e0d00096639","55b7ed07aea7c8190058badb","5604567c0c78b00d0039b191","5605e6f23a93940d002b3e4a","5605f2bba4574a0d00811365","5605f309a4574a0d00811366","5608e3b98aedf50d0004cf8f","5608e4318aedf50d0004cf90","5608e6b5a7cc2f0d00d9754d","5608e6d331beb60d001b6560","5608f879a7cc2f0d00d97580","560b097887b71d0d000d3bd9","560b13cbafa0990d00979545","560b5cbec341310d00de2a01","560b5cd0c341310d00de2a02","566a35b81e08750d00a0c49b","566a3e8503b4b20d00d02a4a","567889d307bf6a0d0083edc8","569c8b7c15bb390d00db6f9d","56b254dc65ddf50d0076ba8f","57a8ebc4cdeea20e001d2a63","57e48a4000c8680e00fae6e7","5808216773557d0f00a1e428","58105ad54a8aa50f00aa4cba","58105bf298aea40f00afa3ba","58105f548a4aed0f00d67536","581061b898aea40f00afa3be","584b3de7e5f3a42300df6ef7","596839a75965d400155bb750"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":["5934fcf39b5614002f2854b0"],"next":{"pages":[],"description":""},"createdAt":"2017-05-17T22:43:17.258Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":10,"body":"<a name=\"create-api-acct\"></a>If you have not yet created a BigCommerce API account for yourself (or your designated developer), use one of the following procedures to create an account and corresponding token:\n\n* [Creating OAuth Accounts](#oauth) – Recommended\n* [Creating Legacy (Basic-Auth) Accounts](#legacy) – Workaround\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"As of Stencil CLI version 1.10.0, the [`stencil init`](/docs/initializing-stencil) command defaults to OAuth authentication. We strongly encourage you to generate all new API accounts/tokens as OAuth, to ensure these accounts' compatibility with all current and planned BigCommerce features. (For example, [uploading themes via the command line](https://stencil.bigcommerce.com/docs/bundling-submitting#push) relies on our [Themes API](https://developer.bigcommerce.com/api/v3/openapi-v3.html#themes), which requires an OAuth store token.) However, note that currently, only the store owner can *create* OAuth accounts/tokens.\\n\\nBigCommerce plans to eventually deprecate [Basic Auth/Legacy API](https://support.bigcommerce.com/articles/Public/Legacy-API-Accounts) accounts/tokens. However, for Stencil themes that you have already initialized/authorized, the [`stencil start`](/docs/launching-stencil) command still supports your existing Legacy API accounts/tokens.\\n\\nAlso, this documentation includes workarounds for creating and using Legacy API accounts/tokens, for stores whose workflow requires that non–store owners be able to create accounts.\",\n  \"title\": \"OAuth Encouraged; Basic Auth Pending Deprecation\"\n}\n[/block]\n## <a name=\"oauth\"></a> Creating OAuth Accounts – Recommended\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Reserved Role\",\n  \"body\": \"Currently, only the store owner can create an OAuth API account according to the instructions below. Also,&#160;note that each store is limited to 50 accounts at a time.\"\n}\n[/block]\n1. Log into the control panel of the store for which you are developing. (Use the store owner's credentials.)\n\n2. From the left nav, select `Advanced Settings` > `API Accounts`.\n\n3. From the resulting `Store API Accounts` page, select the `Create API Account` button.\n\n    <img src=\"https://files.readme.io/97ebeb5-OAuth-Account-Create.png\" alt=\"Creating an OAuth API account\" height=\"100%\" width=\"100%\" style=\"border:1px solid #D1D7E0\">\n\n4. <a name=\"name-by-purpose\"></a>Give your account a `Name` that reflects its purpose. (The BigCommerce platform does not validate this name – so just assign a name that will make the account's purpose clear to you and other store administrators.)\n\n    <img src=\"https://files.readme.io/53ceb1a-OAuth-Account-Create-Name.png\" alt=\"Naming your API account\" height=\"67%\" width=\"67%\" style=\"border:1px solid #D1D7E0\">\n\n5. Under [OAuth Scopes](https://developer.bigcommerce.com/api/#request_scopes), set the `Themes` selector to either `modify` or `read-only`.\n\n    (The `read-only` scope is sufficient to authorize/initialize a Stencil theme. However, the `modify` scope will achieve the same goal, while also authorizing this account to upload themes to the store [from the command line](https://stencil.bigcommerce.com/docs/bundling-submitting#push).)\n\n    <img src=\"https://files.readme.io/8fdfc8c-OAuth-Account-Create-Scopes.png\" alt=\"Selecting a Themes scope\" height=\"35%\" width=\"35%\" style=\"border:1px solid #D1D7E0\"> \n\n6. Click `Save`. As outlined in [this support article](https://support.bigcommerce.com/articles/Public/Store-API-Accounts), doing so will display a modal, from which you can copy your \n`Client ID` and `Access Token` values. It will also prompt your browser to download a `.txt` file that contains your credentials. \n\n    You will need these values to authorize/initialize your Stencil theme. If you're ready to do so now, skip ahead to [Authorizing and Initializing Stencil](/docs/initializing-stencil).\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"As explained in the [support article](https://support.bigcommerce.com/articles/Public/Store-API-Accounts), keep your resulting `Client ID` and `Access Token` values available – either by keeping the control panel's modal open, or by retaining the generated `.txt` file that contains your credentials. \\n\\nThis is your only opportunity to retrieve these values from the control panel. If you lose them, you will need to repeat the whole above procedure before you can authorize your theme.\",\n  \"title\": \"Retain or Repeat\"\n}\n[/block]\n## <a name=\"legacy\"></a> Creating Legacy (Basic-Auth) Accounts – Workaround\n\nTo create a new BigCommerce Legacy API account for your designated developer (or yourself), start here:\n[block:html]\n{\n  \"html\": \"<ol>\\n   <li>Log into the control panel of the store for which you are developing.<p></p>\\n  </li>  \\n  \\n  <li>Follow the procedure documented on this support page: <a href=\\\"https://support.bigcommerce.com/articles/Public/Legacy-API-Accounts#creating\\\" target=\\\"_blank\\\">Legacy API Accounts</a>.\\n  </li>\\n</ol> \\n<br>\\n\\nIf you're ready to use your newly saved Legacy API token to authorize your Stencil theme:\\n\\n<ol start=\\\"3\\\">\\n<li>\\nStay on the control panel's <a href=\\\"https://support.bigcommerce.com/articles/Public/Legacy-API-Accounts\\\">Legacy API Accounts</a> page.<p></p>\\n  </li>\\n\\n<li>\\nIn the appropriate <span class=\\\"inline-code\\\">Username</span> row, select the gear icon at right.<p></p>\\n  </li>\\n\\n<li>From the resulting drop-down, select <span class=\\\"inline-code\\\">Edit</span>.<p></p>\\n</li>  \\n  \\n<li>\\n  In the resulting <span class=\\\"inline-code\\\">Edit Legacy API Account</span> page, select the token in the <span class=\\\"inline-code\\\">API Token</span> field and copy it to your clipboard. Then:<p></p>\\n</li>\\n\\n\\t<ul> <!-- inner list -->\\n\\t\\t<li>If you are a merchant granting an outside theme developer access to your store, provide the developer with the token you've copied. They will need it when <a href=\\\"/docs/initializing-stencil#legacy\\\">Authorizing and Initializing Stencil</a>.<p></p>\\n    </li>  \\n  \\n\\t\\t<li>If you are developing a theme against your own store, keep this token on your clipboard as you proceed to the same <a href=\\\"/docs/initializing-stencil#legacy\\\">Authorizing and Initializing Stencil</a> page.<p></p>\\n    </li>\\n\\t</ul> <!-- inner list -->\\n</ol> \"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"You also have the option to initialize your theme later. To retrieve your token at a later time, see [Copying a Token to Initialize&#160;Stencil](/docs/copying-a-token-to-initialize-stencil#legacy).\\n\\n(Legacy API tokens remain available in your store's control panel. The \\\"Retain or Repeat\\\" warning above, for&#160;OAuth tokens, does not apply to Basic-Auth tokens.)\",\n  \"title\": \"Token Retention\"\n}\n[/block]","excerpt":"","slug":"creating-an-api-account","type":"basic","title":"Creating an API Account"}

Creating an API Account


<a name="create-api-acct"></a>If you have not yet created a BigCommerce API account for yourself (or your designated developer), use one of the following procedures to create an account and corresponding token: * [Creating OAuth Accounts](#oauth) – Recommended * [Creating Legacy (Basic-Auth) Accounts](#legacy) – Workaround [block:callout] { "type": "warning", "body": "As of Stencil CLI version 1.10.0, the [`stencil init`](/docs/initializing-stencil) command defaults to OAuth authentication. We strongly encourage you to generate all new API accounts/tokens as OAuth, to ensure these accounts' compatibility with all current and planned BigCommerce features. (For example, [uploading themes via the command line](https://stencil.bigcommerce.com/docs/bundling-submitting#push) relies on our [Themes API](https://developer.bigcommerce.com/api/v3/openapi-v3.html#themes), which requires an OAuth store token.) However, note that currently, only the store owner can *create* OAuth accounts/tokens.\n\nBigCommerce plans to eventually deprecate [Basic Auth/Legacy API](https://support.bigcommerce.com/articles/Public/Legacy-API-Accounts) accounts/tokens. However, for Stencil themes that you have already initialized/authorized, the [`stencil start`](/docs/launching-stencil) command still supports your existing Legacy API accounts/tokens.\n\nAlso, this documentation includes workarounds for creating and using Legacy API accounts/tokens, for stores whose workflow requires that non–store owners be able to create accounts.", "title": "OAuth Encouraged; Basic Auth Pending Deprecation" } [/block] ## <a name="oauth"></a> Creating OAuth Accounts – Recommended [block:callout] { "type": "warning", "title": "Reserved Role", "body": "Currently, only the store owner can create an OAuth API account according to the instructions below. Also,&#160;note that each store is limited to 50 accounts at a time." } [/block] 1. Log into the control panel of the store for which you are developing. (Use the store owner's credentials.) 2. From the left nav, select `Advanced Settings` > `API Accounts`. 3. From the resulting `Store API Accounts` page, select the `Create API Account` button. <img src="https://files.readme.io/97ebeb5-OAuth-Account-Create.png" alt="Creating an OAuth API account" height="100%" width="100%" style="border:1px solid #D1D7E0"> 4. <a name="name-by-purpose"></a>Give your account a `Name` that reflects its purpose. (The BigCommerce platform does not validate this name – so just assign a name that will make the account's purpose clear to you and other store administrators.) <img src="https://files.readme.io/53ceb1a-OAuth-Account-Create-Name.png" alt="Naming your API account" height="67%" width="67%" style="border:1px solid #D1D7E0"> 5. Under [OAuth Scopes](https://developer.bigcommerce.com/api/#request_scopes), set the `Themes` selector to either `modify` or `read-only`. (The `read-only` scope is sufficient to authorize/initialize a Stencil theme. However, the `modify` scope will achieve the same goal, while also authorizing this account to upload themes to the store [from the command line](https://stencil.bigcommerce.com/docs/bundling-submitting#push).) <img src="https://files.readme.io/8fdfc8c-OAuth-Account-Create-Scopes.png" alt="Selecting a Themes scope" height="35%" width="35%" style="border:1px solid #D1D7E0"> 6. Click `Save`. As outlined in [this support article](https://support.bigcommerce.com/articles/Public/Store-API-Accounts), doing so will display a modal, from which you can copy your `Client ID` and `Access Token` values. It will also prompt your browser to download a `.txt` file that contains your credentials. You will need these values to authorize/initialize your Stencil theme. If you're ready to do so now, skip ahead to [Authorizing and Initializing Stencil](/docs/initializing-stencil). [block:callout] { "type": "warning", "body": "As explained in the [support article](https://support.bigcommerce.com/articles/Public/Store-API-Accounts), keep your resulting `Client ID` and `Access Token` values available – either by keeping the control panel's modal open, or by retaining the generated `.txt` file that contains your credentials. \n\nThis is your only opportunity to retrieve these values from the control panel. If you lose them, you will need to repeat the whole above procedure before you can authorize your theme.", "title": "Retain or Repeat" } [/block] ## <a name="legacy"></a> Creating Legacy (Basic-Auth) Accounts – Workaround To create a new BigCommerce Legacy API account for your designated developer (or yourself), start here: [block:html] { "html": "<ol>\n <li>Log into the control panel of the store for which you are developing.<p></p>\n </li> \n \n <li>Follow the procedure documented on this support page: <a href=\"https://support.bigcommerce.com/articles/Public/Legacy-API-Accounts#creating\" target=\"_blank\">Legacy API Accounts</a>.\n </li>\n</ol> \n<br>\n\nIf you're ready to use your newly saved Legacy API token to authorize your Stencil theme:\n\n<ol start=\"3\">\n<li>\nStay on the control panel's <a href=\"https://support.bigcommerce.com/articles/Public/Legacy-API-Accounts\">Legacy API Accounts</a> page.<p></p>\n </li>\n\n<li>\nIn the appropriate <span class=\"inline-code\">Username</span> row, select the gear icon at right.<p></p>\n </li>\n\n<li>From the resulting drop-down, select <span class=\"inline-code\">Edit</span>.<p></p>\n</li> \n \n<li>\n In the resulting <span class=\"inline-code\">Edit Legacy API Account</span> page, select the token in the <span class=\"inline-code\">API Token</span> field and copy it to your clipboard. Then:<p></p>\n</li>\n\n\t<ul> <!-- inner list -->\n\t\t<li>If you are a merchant granting an outside theme developer access to your store, provide the developer with the token you've copied. They will need it when <a href=\"/docs/initializing-stencil#legacy\">Authorizing and Initializing Stencil</a>.<p></p>\n </li> \n \n\t\t<li>If you are developing a theme against your own store, keep this token on your clipboard as you proceed to the same <a href=\"/docs/initializing-stencil#legacy\">Authorizing and Initializing Stencil</a> page.<p></p>\n </li>\n\t</ul> <!-- inner list -->\n</ol> " } [/block] [block:callout] { "type": "info", "body": "You also have the option to initialize your theme later. To retrieve your token at a later time, see [Copying a Token to Initialize&#160;Stencil](/docs/copying-a-token-to-initialize-stencil#legacy).\n\n(Legacy API tokens remain available in your store's control panel. The \"Retain or Repeat\" warning above, for&#160;OAuth tokens, does not apply to Basic-Auth tokens.)", "title": "Token Retention" } [/block]