Merge pull request #251 from sailpoint-oss/devrel-952

Added service account guide to API docs

products/idn/api/postman-collections.md

@@ -3,18 +3,18 @@ id: postman-collections
 title: Postman Collections
 pagination_label: Postman Collections
 sidebar_label: Postman Collections
-sidebar_position: 6
+sidebar_position: 7
 sidebar_class_name: postmanCollections
 keywords: ['postman']
 description: How to run the APIs in Postman.
 tags: ['postman']
 ---
 
-[Postman](https://www.postman.com/) is a platform you can use to design, build, test, and iterate your APIs. Postman users and teams can create public workspaces they can use to make it easy to access their API collections and environments and get started. SailPoint maintains a [public workspace for the IdentityNow API collections](https://www.postman.com/sailpoint/workspace/identitynow). You can use this workspace to access all the IDN API collections and stay up to date. 
+[Postman](https://www.postman.com/) is a platform you can use to design, build, test, and iterate your APIs. Postman users and teams can create public workspaces they can use to make it easy to access their API collections and environments and get started. SailPoint maintains a [public workspace for the IdentityNow API collections](https://www.postman.com/sailpoint/workspace/identitynow). You can use this workspace to access all the IDN API collections and stay up to date.
 
 ## Run in Postman
 
-Each IDN API version is broken out into a separate collection within the workspace. The following table lists the available IDN API collections. To import a collection into your workspace, select the 'Run in Postman' button for your desired version. Doing so forks the collection into your workspace. 
+Each IDN API version is broken out into a separate collection within the workspace. The following table lists the available IDN API collections. To import a collection into your workspace, select the 'Run in Postman' button for your desired version. Doing so forks the collection into your workspace.
 
 | API | Postman Collection |
 |------|----------------------------|
@@ -30,33 +30,33 @@ When you fork the collection, it is recommended that you check the 'Watch origin
 
 ## Update your collections
 
-SailPoint is often making improvements to the IDN API collections. To keep your workspace in sync with updates to one of SailPoint's public collections, select the ellipse to the right of the collection, and select 'Pull changes'. 
+SailPoint is often making improvements to the IDN API collections. To keep your workspace in sync with updates to one of SailPoint's public collections, select the ellipse to the right of the collection, and select 'Pull changes'.
 
 If there are no changes, you're up to date. If there are changes, the screen lists the changes you're pulling. Select 'Pull changes' again to pull them in.
 
 ## Configure your environment
 
-The SailPoint workspace provides an environment, a set of variables you can use in your requests, that you can fork and pull changes from to stay up to date the same way you can with collections. 
+The SailPoint workspace provides an environment, a set of variables you can use in your requests, that you can fork and pull changes from to stay up to date the same way you can with collections.
 
 To send API requests in Postman, you must authenticate to the APIs. To authenticate to the APIs, you must specify these variables in your Postman environment:
 
-| Environment Variable | Required | Description | 
+| Environment Variable | Required | Description |
 | ----------- | ----------- | ----------- |
 | tenant | Yes | Your IDN tenant, typically your company's name |
 | clientId | Yes | The client ID for the API client or personal access token |
 | clientSecret | Yes | The client secret for the API client or personal access token |
 | domain | No | This optional field is only necessary for those who have a domain in their API URL that isn't "identitynow". |
 
-:::caution 
+:::caution
 
-Don't specify your baseUrl in your environment variables. When you fork an API collection, the baseUrl is automatically set as https://{{tenant}}.api.{{domain}}.com. Setting your baseURl in your environment variables may interfere with this process. 
+Don't specify your baseUrl in your environment variables. When you fork an API collection, the baseUrl is automatically set as <https://{{tenant}}.api.{{domain}}.com>. Setting your baseURl in your environment variables may interfere with this process.
 
 :::
 
-Once you have configured your environment, you can start using Postman with all the endpoints provided in the collections. 
+Once you have configured your environment, you can start using Postman with all the endpoints provided in the collections.
 
 :::tip
 
 Anything you want to change about the Postman collection? We love feedback! Discuss the Postman collection [here](https://developer.sailpoint.com/discuss/t/official-identitynow-postman-workspace/6153).
 
-:::
+:::

products/idn/api/rate-limit.md

@@ -3,7 +3,7 @@ id: rate-limit
 title: Rate Limiting
 pagination_label: Rate Limiting
 sidebar_label: Rate Limiting
-sidebar_position: 5
+sidebar_position: 6
 sidebar_class_name: rateLimit
 keywords: ['rate limit']
 description: There is a rate limit of 100 requests per access_token per 10 seconds for V3 API calls through the API gateway.

products/idn/api/service-accounts.md

@@ -0,0 +1,77 @@
+---
+id: service-accounts
+title: Service Accounts
+pagination_label: Service Accounts
+sidebar_label: Service Accounts
+sidebar_position: 4
+sidebar_class_name: serviceAccounts
+keywords: ['service account']
+description: A guide on how to create service accounts for generating API tokens that can be used in integrations.
+tags: ['Service Account', 'Authentication']
+---
+
+## Service Accounts
+
+Service accounts are identities in IdentityNow that are not a real people.  Their purpose is to provide credentials for automation services that can be managed and controlled separately from real identities.  As a developer of integrations with IdentityNow, the two main advantages of creating service accounts is the ability to scope access to the least privilege necessary to do the job, and to ensure your integration's access doesn't end when you leave your organization.  If you use your user account to generate credentials for integrations, then they are tied to your level of access (i.e. admin) and they can be revoked when you leave the organization, which can cause downtime in your integrations.
+
+## Implementing Service Accounts
+
+Any authoritative source can be used to create and manage service accounts, with Active Directory being a likely choice.  Creating service accounts via Active Directory has the advantage of provisioning your service accounts with unique email addresses that can be used to login to IdentityNow as the service account.  If, however, you don't want to create service accounts using Active Directory, you can use a flat file source to create and manage your accounts.  This section will describe the process of configuring your flat file source to manage service accounts.
+
+### Create a Delimited File Source
+
+Create a new delimited file source and name it "Service Accounts". Then, navigate to the "Account Schema" section and modify the schema as follows.  You can add additional attributes if desired, but these four are good to start with.
+
+![account schema](./img/service-accounts/account-schema.png)
+
+### Creating Service Accounts
+
+To create a service account, you must export the account CSV file and add a new row for each account you want.  Start by downloading the accounts CSV file.
+
+![download schema](./img/service-accounts/download-schema.png)
+
+Then, open the CSV and add a new service account:
+
+- Set the `id` to a unique value that won't be duplicated anywhere in this file (ex. `SA-001`).
+- Set the `name` to quickly describe the account's purpose (ex. `audit01`).
+- Set the `e-mail` to a valid email address that you have access to.  This is important so you receive the IDN invite to set the password and login as the service account. This can be your email address or any other email address you have access to (ex `admin@company.com`).  You can also reuse this email address as many times as you want.
+- Set the `purpose` to a brief description of what this account is used for.  This can help you identify accounts later on when you need to manage and delete old accounts (ex. `Automate monthly audit report`).
+
+Save the CSV and upload it to your source from the "Import Accounts" tab.
+
+![import accounts](./img/service-accounts/import-accounts.png)
+
+If it's successful, you should see one account imported.
+
+![imported account](./img/service-accounts/imported-account.png)
+
+### Make the Source Authoritative
+
+The service account source needs to be authoritative in order to create new identities for each service account.  This will allow us to login as the service account to generate access tokens. To make the service account source authoritative, you must create a new identity profile and link it to your source.
+
+Start by creating a new identity profile named "Service Accounts" that is linked to your Service Accounts source.
+
+![create identity profile](./img/service-accounts/create-identity-profile.png)
+
+Configure the identity profile as desired. Once configured, go to the "Mappings" tab to set up the identity attribute mappings as follows:
+
+- Set `SailPoint User Name` to the `name` attribute
+- Set `Work Email` to the `e-mail` attribute
+- Set `Last Name` to the `name` attribute
+- Set `First Name` to the `name` attribute
+
+![mappings](./img/service-accounts/mappings.png)
+
+Click "Save" and then "Apply Changes" to create the first identity from the service accounts source.  Once the identity is created, you might need to manually send the invite.  To do so, go to the identity list and search for the accounts name (ex. `audit01`).  
+
+![invite](./img/service-accounts/invite.png)
+
+If you have not received the invite, check your junk folder or deleted folder, as it might have been automatically filtered by your email provider.  Once you receive the invite, follow the steps to register your service account.  Once your user is registered, login as the service account with the password you created for it.
+
+![login](./img/service-accounts/login.png)
+
+### Permissions and Access Tokens
+
+New service accounts will be given the basic "user" level.  Depending on what you need your service account to do, you will need to modify the user level appropriately.  Please see the [user level permissions](./authorization.md#user-level-permissions) for more information on user levels and how to set them.
+
+Once your service account has the appropriate user level, you can now generate [personal access tokens](./authentication.md#personal-access-tokens) (PAT) from the service account to fulfill the needs of your integrations.  You can further refine the access of your personal access tokens by applying [scopes](./authorization.md#scopes) to each PAT that you create.

products/idn/api/standard-collection-parameters.md

@@ -3,7 +3,7 @@ id: standard-collection-parameters
 title: Standard Collection Parameters
 pagination_label: Standard Collection Parameters
 sidebar_label: Standard Collection Parameters
-sidebar_position: 4
+sidebar_position: 5
 sidebar_class_name: standardCollectionParameters
 keywords: ['standard collection parameters']
 description: Many endpoints in the IdentityNow API support a generic syntax for paginating, filtering and sorting the results.

products/idn/sidebar.js

@@ -17,6 +17,10 @@ const sidebars = {
           type: 'doc',
           id: 'api/authorization',
         },
+        {
+          type: 'doc',
+          id: 'api/service-accounts',
+        },
         {
           type: 'doc',
           id: 'api/standard-collection-parameters',