SAM.gov_User Guide_2022 v3.01.pdf

System Account User Guide

Version 3.01

Document Control: Version History

Version ID Date Description of Changes Authored By

1.0 Original published dra� Integrated Award

Environment

2.0 Feb 2021 Updates to guidance Integrated Award

Environment, Office of Stakeholder Engagement

3.0 Nov 2021 Extensive revisions based on user

feedback. New tools for users to prepare to apply for and to manage API connections. New glossary of terminology.

Integrated Award Environment, Office of Stakeholder Engagement

3.01 Jan 2022 Updates to include how to manage

system account deactivation

Integrated Award Environment, Office of Stakeholder Engagement

U. S. General Services Administration 1

Table of Contents How to Use this Guide

Overview of System Accounts, Individual Accounts, and API Keys Whatʼs the difference between an individual account and system accounts?

Which type do I need?

What else do I need to know before I make a request for a system account or get an individual account API key?

Type of Connections and Rate Limits Interface Specifications (for system accounts only) Permissions for Data Access (for system accounts only)

Individual Account API Key Getting an Individual Account API Key

Accessing the Workspace Requesting an Individual Account API Key (Public API Key)

Managing an Individual Account API Key Individual Account API Key Security and Viewing Individual Account API Key Rotations

API Key Rotation Tips for Individual Accounts Removing an Individual Account API Key

System Accounts, System Account Passwords, and System Account API Keys Requesting Federal System Accounts

Accessing the System Account Workspace Requesting a System Account Role Viewing System Accounts in Your Workspace Requesting a New System Account Reviewing Status

Requesting Non-Federal System Accounts Accessing the System Account Workspace View Available System Accounts Requesting a New System Account Reviewing Status

Managing System Accounts About System Account Passwords

Getting a System Account Password

Administration 2

Resetting a System Account Password About System Account API Keys

Getting a System Account API Key System Account API Key Rotation

API Key Rotation Tips for System Accounts Other System Account Management Tasks

Editing System Accounts Requesting a Rate Increase Renewing System Accounts System Account Deactivation

For More Help Help Resources Troubleshooting

Appendix A: Domain roles and permissions

Appendix B: Account Request Preparation Checklist

Appendix C: Account Management Checklist

Appendix D: Glossary of Terminology

How to Use this Guide The purpose of this guide is to provide information to users of individual accounts and systems accounts that access SAM.gov information via Application Programming Interface (API).

Throughout this guide, youʼll see a few options to help you get the most out of this information.

● Italicized words or phrases indicate important terminology. You can find a definition in the text or in a glossary at the end of this document.

● A stopwatch icon (⏱) tells you how you can take a shortcut to another part of the guide or skip to other information.

● Links to other resources, such as Frequently Asked Questions (FAQs) and websites, are included where applicable.

● Helpful tools and checklists in the appendices help you prepare for and manage your individual account API Key or system account and system account API key.

Administration 3

Overview of System Accounts, Individual Accounts, and API Keys System accounts and individual accounts are two options for connecting to SAM.gov for data transactions on a repeated basis. You need keys, called system account API keys or individual account API keys, to access these connections depending on the type of connection you select.

Whatʼs the difference between an individual account and system accounts?

Individual Account Non-Federal System Account Federal System Account

➔ For individual users; this is the same as your SAM.gov user account.

➔ Access to an Application Programming Interface (API) to view public data. Can be accessed by both federal and non federal SAM.gov users.

➔ Allows you to systematically pull detailed information from SAM.gov using different parameters.

➔ Recommended if you need to request real-time, limited public data through a Representative State Transfer (REST) API service.

➔ Features:

○ Contains your own personal information

○ May stay with you even when your role in your organization or the permissions you need to do your job change (as long as

➔ For systems to use; must be requested

➔ An account for systems not managed by the federal government that need to connect via REST API.

➔ Allows you to systematically pull detailed information from SAM.gov using different parameters.

➔ Recommended if you request frequent or large amounts of public data through a REST API service.

➔ Features:

○ Represents a particular information technology (IT) system

○ Is primarily for systems that need to automate the pull of data through extracts or web services

➔ For systems to use; must be requested

➔ An account for systems owned by the federal government that need to connect via a REST API.

➔ Allows you to systematically pull detailed information from SAM.gov using different parameters.

➔ Required to request For Official Use Only (FOUO) or Sensitive data access specifically through a REST API service.

➔ Features:

○ Represents a particular federal

IT system

○ Can request access to view sensitive data through search or extracts

○ Is primarily for systems that need to either send data to

Administration 4 your department still allows you to access the same information if you move around within it)

○ Is useful if multiple users in your organization need to access the same extract or web service

SAM.gov (such as a contract writing system) or automate the pull of data through extracts or web services

○ Is useful if multiple users in your organization need to access the same extract or web service

Which type do I need?

System account API keys are for any system that needs to connect to SAM.gov for large data transactions on a repeated basis. There are two types of system accounts: federal and non-federal.

Individual account API keys are for individuals that need to connect to SAM.gov for a limited number of data transactions on a repeated basis.

You do not need either of these if you only want to download prepared data extracts. Any user can go directly to SAM.gov to initiate a search and view public data.

However, if you or your system need to connect to SAM.gov information regularly and repeatedly, an individual account API key or system account API key may be your best option. Please note that there is some data available via API that is not available in data extracts (e.g. federal hierarchy or PSCs and location services).

As described above, everyone with a SAM.gov account can get individual-level API access. You just need to request an individual account API key to do this. If you need to connect through a system, you will need to specifically request a system account, and you will need to get and use a system account API key to access APIs for data.

⏱For more information about how to use data extracts, view this video.

To learn more about system accounts and APIs, continue with this guide.

What else do I need to know before I make a request for a system account or get an individual account API key?

Consider:

● The type of connection and rate limit you need

● Interface specifications

● Permissions for data access

U. S. General Services Administration 5 https://www.sam.gov https://www.sam.gov https://www.fsd.gov/gsafsd_sp?id=kb_article_view&sysparm_article=KB0030309

⏱ If you are confident you have the information you need to make the request that best suits you, you can skip to the instructions for making your individual account API key or system account request.

Type of Connections and Rate Limits

A connection refers to sending and receiving HTTP requests or responses for data. A rate limit is the number of allowed new connections in a specific timeframe (e.g. per second, minute, hour, day).

To better understand whether you need to use an individual account or a system account to access data, consider the number and type of connections you need:

Any user can request an individual account API key from their profile page. This API key can be used to get, or pull, public data from SAM.gov with a limited number of requests per day (see the table below).

If you need more connections for more people, request a system account. This requires additional steps and validations to get increased request volume and data access.

Keep in mind that a user with a system account is allowed to have one system account API key and one individual account API key. A user with only an individual account (non-system) may only have one individual account API key.

Connecting Source Type of Connection Default Rate Limit

Non-federal individual user not associated with an entity

Individual account API key 10 requests/day

Non-federal individual user associated with an entity

Individual account API key 1,000 requests/day

Federal individual user Individual account API key 1,000 requests/day

Non-federal system System account API key 5,000 requests/day

Federal system System account API key 10,000 requests/day

The rate limits listed are set by default. Only those with a federal system account can request an API key rate limit increase. These exception requests are handled on a case

Administration 6 by case basis, based on business justification, and may be revoked if itʼs determined the exceptions are putting a strain on Integrated Award Environment (IAE) systems or are not being used to the degree requested.

Interface Specifications (for system accounts only)

Before requesting a system account, please review the specifications and requirements for any connection you need. Specifications include: access controls, send and response parameters, format, and any specific system requirements. All request and response details for the REST APIs are documented on open.gsa.gov.

Permissions for Data Access (for system accounts only)

If you decide that you need a system account, establish what data you have a business reason to access, and what actions you will take with the information (read or write).

● If you are just pulling data, or using GET calls, then you will only need read permissions for the data (federal and non-federal users).

● If you are writing, sending, or using POST and PUT calls, then you will need write permissions (federal users only).

● Be aware that only federal accounts can access For Official Use Only (FOUO) or Sensitive data permissions, and only federal accounts are allowed to write data. Non-federal users can only select the public read permissions when submitting a system account request.

Find your type of account on the table below to see what kind of access you can request.

Type of Account Read Permissions Allowed Write Permissions Allowed

Non-federal system accounts

Yes; Public Read permissions for GET calls No

Federal system accounts

Yes; Public Read and FOUO/Sensitive Data GET calls

Yes; Public Write and FOUO/Sensitive Data POST or PUT calls.

When you request a system account, you will be presented with a list of the SAM.gov domains you can get information from. Each domain represents a data set and has permissions specific to the domain.

Knowing which domains and permissions you need will help you complete your request quickly and accurately.

⏱ Review the data sets and permissions allowed for each domain in Appendix A of this guide.

U. S. General Services Administration 7 https://open.gsa.gov/

If youʼre interested in getting an individual account API key on your individual account, follow the steps in Getting an Individual Account API Key, below.

⏱If you will only use data through the website, or front end, then you do not need an individual account API key and can use data extracts and reports instead. If you plan to connect via a system account, you will need a system account API key. To proceed to instructions for requesting a system account, skip to that section now.

Remember, you can have both an individual account API key and a system account with system account API key.

Administration 8

Individual Account API Key On SAM.gov, an individual account API key is referred to as a public API key. These terms are interchangeable and you may see both terms used on the website and in this guide. The term public refers to the type of data—public data—you can view with an individual account API key.

You can use the Account Request Preparation Checklist at the end of this guide to help as you gather the information necessary to complete this process. There are two steps for getting an individual account API key.

Getting an Individual Account API Key

Accessing the Workspace

Before you can request an individual account API key, you must have a SAM.gov user account (individual account). Select “Sign In” on the header of any SAM.gov page, and complete the account form. If you already have a user account, you can skip this step, sign in using your existing account, and continue with the next instructions.

A�er you have an individual SAM.gov user account, you will have access to the Workspace where you can manage specific data or items.

You can request your individual account API key from your Profile page within the Workspace:

1. Sign into SAM.gov.

2. Your Workspace page will be displayed. If you are on another page, navigate to Workspace using the Workspace link at the top of any page.

Administration 9

3. On your Workspace, select the “Profile” label to display your account details page.

Requesting an Individual Account API Key (Public API Key)

1. On your Account Details page, navigate to the section titled Public API Key (Remember: public API key and individual account API key are the same thing).

2. Select Request API Key.

You now have access to an individual account API key. You can use it to complete a limited number of calls through the site interface connections documented on open.gsa.gov and the table in this guide.

This concludes the information about requesting an individual account API Key. Continue to the next section to learn about managing your individual account API key.

Managing an Individual Account API Key Youʼll need to take action periodically to manage your individual account API key. Managing your key properly will help ensure you can use it to access information on an ongoing basis. The following topics will help you manage your individual account API key:

● Individual Account API Key Security and Viewing

U. S. General Services Administration 10

● Individual Account API Key Rotations

● Individual Account API Key Rotation Tips

● Removing an Individual Account API key

Individual Account API Key Security and Viewing

A�er your initial API key request, for security purposes, the API key will be hidden. Ongoing, you will need to unhide and view it on this page so that you can use it to access APIs, retrieve rotated API keys, etc. Read on for steps to unhide your API key.

Hereʼs how you can view it:

1. Select the eye icon to view your API key. A one-time password will be sent to the email address on the account for your individual account.

2. Retrieve the password from your email and enter it into the Enter One-time Password field in the pop up on the Public API Key section of your Account Details page.

3. Select Submit to view the Individual Account API key.

Administration 11

Your API key will display in the Public API Key section. You can use this process anytime you need to view your individual account API key.

Individual Account API Key Rotations

For security reasons, individual account API keys must rotate every 90 days. A new key will be auto-generated for you before the current key is out of date. Hereʼs what happens:

1. You will receive a series of email notifications starting 15 days prior to when the current key will be out of date, notifying you of the upcoming need for rotation. Always read all emails about your individual account API key so you do not miss important messages!

2. 15 days before your current key is out of date, a replacement API key will auto-generate and display in the Public API Key section of your Profile page, below the current key.

You can tell the current key from the replacement key by the number of days indicated until expiration. The one with fewer days is the current key–the one youʼve been using. The one with more days–the replacement key–is the key that will rotate in when the current key is out of date.

3. Retrieve and begin to use your replacement individual account API key as soon as possible a�er it is auto-generated. Both the replacement and current key will be active (you can use either) during the 15-day window before the current key is out of date.

4. The current key will go out of date at midnight at the end of the 14th day, and the replacement key will become the current key. Only the new, current key will be visible a�er the rotation has occurred (this cycle repeats for the life of your individual account or until you remove the individual account API key).

Administration 12

Below is an example of a timeline for individual account API key rotation. Your rotation cycle will start on whatever date you request your individual account API key.

API Key Rotation Tips for Individual Accounts

➔ You do not need to do anything to request a replacement key or start the API key rotation. The backup key is auto-generated by SAM.gov as part of the API key rotation workflow in the system.

➔ Your only task for API key rotations is to view and input the key that is current during the time period when you want to connect through an API. In order to stay up to date, you must go get the replacement key a�er it is auto-generated so you can use it once the current key rotates out. During the 15-day replacement period, you may use either key to connect.

➔ If your individual account API key becomes out of date before you have retrieved the replacement, you can still retrieve your replacement API Key from the “Workspace” page under “Profile” in your SAM.gov any time. The replacement key will take effect immediately.

➔ API key rotation will trigger a series of reminder emails to you. The purpose of these emails is to remind you to retrieve your new (replacement) key. We advise you read each email to understand what actions you need to take, especially if you have more than one type of account with SAM.gov. You can disregard emails for individual account API key rotations once you have retrieved your replacement key.

Administration 13

⏱Look for more tips on API key rotations and find out how to get help in the appendix.

This concludes the information about individual account API key rotations.

Removing an Individual Account API Key

You may wish to remove your individual account API key at some point. If you have had your API for more than 24 hours, you can remove it at any time using the steps below. For security reasons, if you want to remove an individual account API key that you recently requested, you will have to wait 24 hours from when you made the API key request before you ask to remove it. You will no longer receive reminder emails about rotating your API key a�er you remove it. You may remove it any time you choose a�er that period by following these steps:

1. Go to the Public API Key section of your profile page. Select Remove API Key.

2. Verify through the popup window that will display that you want to remove the API key.

a. When you select “Yes, remove API key”, the API key will be deactivated and can no longer be used for connecting to the site.

b. When you select “No, keep API key”, the popup will be dismissed and the API key will continue to be available.

Administration 14

⏱If you are an individual account API key user who does not also use a system account, this is the end of your section of the guide.

You can view tools and more help in the Appendix. For comprehensive FAQs, please search fsd.gov.

U. S. General Services Administration 15 https://www.fsd.gov/

System Accounts, System Account Passwords, and System Account API Keys Remember, there are two types of system accounts: federal and non-federal.

As explained in the permissions section in this guide, only federal departments or independent agencies may request federal system accounts. And, only federal accounts are permitted access to FOUO or Sensitive information. Since federal systems are allowed to request access to non-public data, there are additional access controls and security approvals integrated into the request process.

You can use the Account Request Preparation Checklist at the end of this guide to help you prepare the information necessary to complete non-federal and federal system account processes.

⏱If you only want to learn about non-federal system accounts, you can skip to that section now.

To learn more about federal system accounts, continue.

Requesting Federal System Accounts Youʼll need to take several steps to get a system account.

These topics will guide you through these steps:

● Accessing the System Account Workspace

● Requesting a New System Account

● Reviewing Status

⏱If you know which topic you want to explore, you can skip to it by selecting the topic name linked to that section. If you have never requested a federal system account, we recommend starting with the first topic.

Administration 16

Accessing the System Account Workspace

The first step to requesting a federal system account is to get a SAM.gov user account as a federal user. Select “Sign In” on the header of any page, and complete the account form using your federal government email address.

A�er you complete the account setup, you will have access to the Workspace where you can manage specific data or items. Your Workspace is tailored to you based on roles, permissions, and personal preferences.

You can view your federal roles in the Profile section of your Workspace, Administration 17

Requesting a System Account Role

As a federal user who wants to establish a system account, you must request a system account role.

System account roles can only be granted by an agencyʼs system account administrator. You can check the User Directory in the SAM.gov Workspace to find your system account administrator.

The two roles you can choose from for system accounts are:

System Account Manager System Account Administrator

You can:

● Edit system accounts that you are responsible for

● Submit a request for a system account to be reviewed by the System Account Administrator

You cannot:

● Assign or approve roles

Your agency system administrator and GSA must approve the system account request before the system account can be created by GSA.

The manager will receive emails about the system, including but not limited to system account renewals and API key rotation notifications.

You can:

● Submit a request for a system account to the General Services Administration (GSA) for approval

● Assign and approve roles for other people who will be managing your federal systems

The administrator will receive emails about the system, including but not limited to system account renewals and API key rotation notifications.

To request one of these roles, you must email someone in your department or agency who already has this role. Request the role directly by email, and include a description of your business need to access the information. Do not use the role request feature in your Workspace. In the event that no one at

Administration 18 your agency has this role, the Chief Information Officer (or similar executive) for your department or independent agency must appoint someone.

Note: Please do not request roles or ask about the status of a role request with the Federal Service Desk; they are only able to assist with technical issues and do not have the ability to grant you a role in SAM.gov. However, you can go to fsd.gov and search the FAQs for more information about getting and managing roles.

Viewing System Accounts in Your Workspace

Once you have a System Account Administrator or System Account Manager role, you can view existing system accounts available for you to access in your Workspace. If there are other system accounts already in your federal hierarchy level, you can view and use them.

1. A�er you have signed in to SAM.gov, navigate to your Workspace from the header on any page.

2. Select System Accounts from the widgets to view details for your system accounts.

3. This page is known as your Tier 2 Workspace for System Accounts. Review this page for any system accounts to which you are already connected through your role or agency.

U. S. General Services Administration 19 https://www.fsd.gov/gsafsd_sp?id=gsa_search&spa=1&q=request%20a%20role https://www.fsd.gov/gsafsd_sp?id=gsa_search&spa=1&q=request%20a%20role

Requesting a New System Account

When you view the system accounts available in your Workspace, you may decide to set up, or request, a new system account. You can do that by following these steps:

1. From the Tier 2 System Accounts Workspace, select New Account.

On the new account request screens, you can track your progress by viewing the navigation menu.

System Information

2. Enter details for the system account you wish to establish:

a. System Account Name: Unique name that helps you and others distinguish the account from any other managed by you or others in your organization.

b. Interfacing System Name and Version: Actual full name of the connecting system and version number.

Administration 20

c. System Description and Function: The business reason for your system connection. This includes any justification for access to non-public data and any justification for sending data to our system.

3. Select Next to continue. Red text will be displayed by any field that is incomplete or fails validation. Instructions let you know what to update (see an example, below). Correct the issue to continue.

Please be aware that selecting Cancel at any point in the process will delete the current edits and return you to the Tier 2 System Account Workspace.

Organization Information

4. On the next screen enter the specific organization information for the new system account you wish to establish (see example, below):

Administration 21

a. Organization: Required. The screen will display your organizationʼs hierarchy, as permitted by your role. If your role is with a specific sub-tier or office, you will only be able to associate your account to that level. A system account administrator at a higher level will be able to manage your account and grant higher access if needed. You must enter one organization/agency, sub-tier, or office for your system account using the agency picker.

b. System Account Administrators: Required. These specific users will be listed with the account and identified as points of contact (POCs) for any communications about the system account. You will only see available administrators within your agency who have the system account administrator role already. Choose administrators from the list. We recommend organizations list at least two administrators so that there can be a backup. If you don't know the system account administrator, use the User Directory to locate one in your agency. This step must be completed in order for administrators to address your new system account request.

c. System Account Managers: Optional. Users you include here will be listed with the account and identified as points of contact (POCs) for any communications about the system account. We recommend organizations list at least two managers.

5. When all fields are complete, select Next to continue. If you need to return to the previous section, select the item from the table of contents or the Previous link at the end of the page.

To delete the dra� in progress and return to the Tier 2 Workspace page, select the Actions drop

Administration 22 down and then select Delete.

Permissions

6. On the next screen (see example, below), select the specific permissions for the system account you wish to establish:

a. In advance, review Permissions for Data Access and Appendix A to identify the specific permission requirements for your system. If you do not properly justify the permission you are requesting, the account request will be rejected.

b. Review the Terms of Use before you submit your account request. View the Terms of Use on this screen by selecting Terms of Use. A popup window will display the full text.

c. Select the correct overall Federal Information Processing Standard (FIPS) categorization from the drop down menu.

7. When all fields are complete, select Next to continue. If you need to return to the previous section, select the item from the table of contents or the Previous link at the end of the page.

U. S. General Services Administration 23 https://csrc.nist.gov/publications/detail/fips/199/final

What do the white and gray checkboxes mean?

White boxes indicate permissions that are available to choose in the domain they are listed under.

Gray boxes indicate permissions that are not available to choose in the domain they are listed under.

Administration 24

Security Information

8. On the next screen (see example, below), enter the specific security information for the system account you wish to establish:

a. IP Address: This should be the specific Internet Protocol (IP) address or addresses for the connecting system. If the IP is masked by Classless Inter-Domain Routing (CIDR), enter the range here.

b. Type of Connection: Select any connection the system will use, such as REST API.

c. Physical Location: Specify the primary physical location of the system.

d. Security Official: Enter contact information for your agency Information System

Security Officer (ISSO) or other security personnel. Do NOT input the information for the GSA security reviewer.

9. When all fields are complete, select Next to continue. If you need to return to the previous section, select the item from the table of contents or the Previous link at the end of the page.

Administration 25

Authorization

10. On the next screen (see example, below), enter the specific authorization for the system account you wish to establish. For federal system account requests, supporting Documentation must include Authority to Operate showing that the system meets security, privacy, and other federal standards for data access.

11. When all fields are complete, select Review to continue. If you need to return to the previous section, select the item from the table of contents or the Previous link at the end of the page.

12. Before final submission, review the application. Select Edit to change any section.

13. Select Submit a�er all sections are completed.

14. A�er selecting Submit, you must review all sections included in the terms of use document. At the end of the review, you must accept the terms of use by entering a one-time password sent to the email address on your own user account.

Administration 26

15. A�er accepting the terms of use, you will be returned to the SAM.gov home page.

Return to your workspace and select the System Account Widget. Your submitted account request will appear in the results section with a status (initial status depends on your role and the permissions you selected for the account).

Continue to Review Status for more on the approval process of your request.

Reviewing Status

The most current status of a system account can be seen on the Tier 2 Workspace.

Request rejections: If at any point a system account request is rejected, you will receive an email notification and the request will be moved back to dra� for editing. You can resubmit the request a�er you complete edits.

Notifications: All changes to status are recorded in the history of the system account request and automated email notifications about status changes are sent to the submitter, associated system account managers and administrators, and those reviewing the request.

TImeline & follow up: The time required to process each status depends on the type of account (i.e.

public data) and the permissions in the request.

Administration 27

● If your status is “Pending Review” check with your System Account Administrator.

● If your status is in “Pending Permissions Review” for more than a couple of business days, you can create an FSD ticket to request a status update on your request.

This is the sequence used to move your request through the approval process:

Step Status Description

1 DRAFT System Account Managers and System Account Administrators can edit the dra�.

2 PENDING REVIEW If the original request was submitted by a System Account Manager, the request is now awaiting approval from the listed System Account Administrators, who will review and approve (or reject) the systemʼs business need for access.

3 PENDING PERMISSIONS REVIEW GSA checks the accountʼs requested data access.

4 PENDING APPROVAL GSA conducts a security review. If your account is not approved you will be notified via email and your request will not move forward.

5 PUBLISHED The request has been approved and the account can now be used to access the data as requested.

This concludes this information about how to request a federal system account.

If you need to request a non-federal system account, start with the next section in this guide.

⏱ To learn more about system account passwords, skip to this step.

To learn more about system account API keys, skip to this step.

To learn more about system account management, skip to this step.

Administration 28

Requesting Non-Federal System Accounts Remember, there are two types of system accounts: federal and non-federal.

A non-federal system account is for any system managed by an entity or other non-federal organization. As explained in the permissions section in this guide, non-federal entities may request read permissions of public data.

You can use the Account Request Preparation Checklist at the end of this guide to help you prepare the information necessary to complete system account processes.

⏱If you only want to learn about federal system accounts, you can skip to that section now.

To learn more about non- federal system accounts, continue.

Follow these steps to request your account.

These topics will guide you through these steps:

● Accessing the System Account Workspace

● Requesting a New System Account

● Reviewing Status

⏱If you know which topic you want to explore, you can skip to it by selecting the topic name linked to that section. If you have never requested a non-federal system account, we recommend starting with the first topic.

Administration 29

Accessing the System Account Workspace

The first step to requesting a non-federal system account is to get a SAM.gov user account. Select “Sign In” on the header of any page, and complete the account form.

A�er you complete the account setup, you will have access to the Workspace where you can manage specific data or items. Your Workspace is tailored to you based on roles, permissions, and personal preferences. To request a non-federal system account, you will need to look for the System Accounts widget.

No specific roles or permissions are needed beyond the basic user profile.

View Available System Accounts

Once you have a SAM.gov account, view the system accounts that may be available to you currently:

1. A�er you have logged in, navigate to your main Workspace from the header on any page.

2. In the System Accounts widget, you will see all the accounts that you have submitted as well as the system accounts for which you are listed as the Other System Account Holder. Other System Account Holder is a backup designation in case the primary requester of that system account is unable to access it. Select the System Accounts label from the widget to go to your detailed system accounts view.

Administration 30

3. This page is known as your Tier 2 Workspace for system accounts. Once you have created, submitted, or been associated with a System Account, you will be able to see those accounts on this page.

Requesting a New System Account

1. From the Tier 2 system accounts Workspace page, select New Account to start the new system account request process.

On the new account request screens, you can track your progress by viewing the navigation menu.

Administration 31

System Information

2. Enter the details for the system account you wish to establish:

a. System Account Name: Unique name that helps you and others identify the account from any other you or others in your organization manage

b. Interfacing System Name and Version: Actual full name of the connecting system and version number

c. System Description and Function: The business reason for your system connection. This includes any justification for access to data.

3. When all fields are complete, select “Next” to move to the next section. Red text will appear by any field that fails validation with information on what needs to be updated. Correct the issue to move forward.

Be aware that selecting “Cancel” at any point in the process will delete the current edits and return you to the Tier 2 System Account Workspace.

Administration 32

Entity Information

4. Enter the specific entity information for the system account you wish to establish:

a. Entity: If this connection is for an entity with a current public entity registration, then you can enter that entity here using the entity picker. You can enter a single entity with a current, public entity registration. If this is not an entity with a current public registration, then you can leave this blank.

b. Other System Account Holder: Required. You must enter the email address of another non-federal user who is registered with the site. This user will be considered the joint account holder for this account and will have permission to manage this account. This

Administration 33 user will also be the first-level approver for the account once you submit the account.

You cannot enter your own email address in this field. You will see an error message in red next to the field if you do not enter a valid email address that meets all the above requirements. The reason you must enter another email address here is so that if, for any reason, you leave your company or lose access to your account, the owner of the other email address can maintain access to the system account for your entity.

5. When all fields are complete, select “Next” to move to the next section. If you need to return to the previous section, select the item from the table of contents or the “Previous” link at the end of the page.

Be aware that selecting “Actions” and then “Delete” from the dropdown will delete the dra� in progress and route you back to the Tier 2 Workspace page.

Administration 34

Permissions

6. Enter the specific permissions for the system account you wish to establish:

a. Choose the permissions you want to request. You can review the previous section titled “Permissions for Data Access” and Appendix A: Domain Roles and Permissions to identify the specific permission requirements for your system in advance of making your request. If the requested permission is not properly justified, the account request will be rejected.

7. Selecting “Terms of Use” will open a popup window that displays the full text of the terms of use you will be asked to acknowledge and agree to upon system account submission.

8. When all fields are complete, select “Next” to move to the next section. If you need to return to the previous section, select the item from the table of contents or the “Previous” link at the end of the page.

Administration 35

What do the white and gray checkboxes mean?

White boxes indicate permissions that are available to choose in the domain they are listed under.

Gray boxes indicate permissions that are not available to choose in the domain they are listed under.

Administration 36

Security Information

9. Enter the specific security information for the system account you wish to establish:

a. IP Address: This should be the specific external Internet Protocol (IP) address or addresses for the system connecting. If the IP is masked by Classless Inter-Domain Routing (CIDR), then the range should be entered here.

b. Type of Connection: Any connection the system will use should be selected, such as REST API, etc.

c. Physical Location: The primary physical location of the system.

d. Security Official: Your entityʼs System Security Officer (ISSO) or other security personnel (NOT the GSA security reviewer).

10. When all fields are complete, select “Next” to move to the next section. If you need to return to the previous section, select the item from the table of contents or the “Previous” link at the end of the page.

Administration 37

Authorization

11. Attach the specific authorization for the system account you wish to establish. The Supporting

Documentation is optional (official documentation showing the system meets a prescribed set of security and privacy standards).

12. When all fields are complete, select “Review” to move to the next section. If you need to return to the previous section, select the item from the table of contents or the “Previous” link at the end of the page.

13. Before final submission, review the application. Select “Edit” to change or update any section.

14. The final “Submit” selection will be available a�er all sections are completed.

Administration 38

Administration 39

15. A�er selecting “Submit,” you will be routed to accept the terms of use.

16. You must review all sections included in the terms of use document.

17. At the end of the review, you must accept the terms of use through a one-time password sent to the email address of your user account.

Administration 40

18. A�er accepting the terms of use, you will be returned to the SAM.gov home page.

Return to your workspace and select the System Account Widget. The submitted account request will appear in the results section with a status of “Pending Review.” Continue to the “Review Status” section below for more on the workflow steps the request will go through.

A�er this step, your request has been submitted and will go into an approval workflow.

Reviewing Status

The most current status of a system account can be seen on the Tier 2 Workspace.

Request rejections: If at any point a system account request is rejected, you will receive an email notification and the request will be moved back to dra� for editing. You can resubmit the request a�er you complete edits.

Notifications: All changes to status are recorded in the history of the system account request and automated email notifications about status changes are sent to the submitter, associated system account managers and administrators, and those reviewing the request.

TImeline & follow up: The time required to process each status depends on the type of account (i.e.

public data) and the permissions in the request.

● If your status is “Pending Review” check with your System Account Administrator.

● If your status is in “Pending Permissions Review” for more than a couple of business days, you can create an FSD ticket to request a status update on your request.

This is the sequence used to move your request through the approval process:

Step Status Description

1 DRAFT The user who submitted the account and the Other System Account Holder listed on the account can edit the dra�.

2 PENDING REVIEW The Other System Account Holder listed on the account will review and approve (or reject) the systemʼs business need to access the data requested in the format requested.

3 PENDING PERMISSIONS REVIEW GSA checks the accountʼs requested data access.

4 PUBLISHED The request has been approved and the account can now be used to access the data as requested.

Administration 41

All changes to status are recorded in the history of the system account request and email notifications to the submitter, the Other System Account Holder, and those reviewing are sent automatically.

This concludes this information about how to request a non-federal system account.

⏱ To learn more about system account passwords, skip to this step.

To learn more about system account API keys, skip to this step.

To learn more about system account management, skip to this step.

Administration 42

Managing System Accounts Youʼll need to take action periodically to manage your system account and system account API key.

Proper management will help ensure you can use it to access information on an ongoing basis. The following topics will help both federal system account and non-federal system account holders with these management tasks:

● Getting a System Account Password

● Resetting a System Account Password

● About System Account API Keys

● Getting a System Account API Key

● System Account API Key Rotation

● Tips for System Account API Key Rotation

● Other System Account Management Tasks

● Editing System Accounts

● Requesting a Rate Increase

● Renewing System Accounts

● System Account Deactivation

You can use the Account Management Checklist at the end of this guide to help you manage your system account throughout the year.

About System Account Passwords

Do you need a system account password? Yes. You will use it for two functions: accessing your system account, and connecting to APIs (where required).

Connecting to APIs: For your federal or non-federal system to connect, you may need a system account password, a system account API key, or both. Different APIs may require a password in addition to a key, while others may not.

Each API has its own requirement outlined at open.gsa.gov. For example, the Contract Opportunity Interface API requires the user to pass both the System Account Password and the API Key, whereas, one of the Entity domain APIs requires just the API key and not the password. You can view the individual requirements for APIs at open.gsa.gov/api. Select “View API Documentation” for APIs you want to connect to using your system account.

Accessing your system account: You do not need to have a password to generate a replacement API key; that happens automatically in API key rotations. However, you do need

U. S. General Services Administration 43 https://open.gsa.gov/api/ to keep your password up to date so that you can access your system account and view your API key.

Getting a System Account Password

1. Login and navigate to your Workspace from the header of any SAM.gov page.

2. Select System Accounts from the widgets to view your system account details.

3. Navigate to the system account you want to set a password for. Select the name of the system account, which will open the account details page. The account details page includes all the information about the account that you provided when requesting it, as well as a place to establish and maintain a password.

4. On the account details page, scroll to System Account Password to create a password for the account. For security reasons, the password should meet the following requirements:

● Be at least 12 characters

● Have at least 1 uppercase character

● Have at least 1 lowercase character

● Have at least 1 numeric digit

● Have at least 1 special character: !@#$%^&*_+

● Should not contain part of the System Account name

● Should not be a common or generic password

● Should not be one of the past 24 passwords that were used on the account

Administration 44

5. Once your chosen password meets the parameters, select Save. A success message will appear, and options to reset the password will be displayed for future password changes.

Resetting a System Account Password To continue using the system account, you must reset the password on the account every 90 days.

Note: System account passwords and system account API keys expire and rotate on different schedules. Resetting your password does not generate a new key (keys

Administration 45 are auto-generated). Please note that if your password has expired, that means you canʼt use it to view your system account or API key (see below). Also, APIs which are required by open.sam.gov to use both a key and a password will not be able to connect to SAM.gov. If this happens, you must resolve either your expired password, your replacement API key, or both, depending on the timing of your system account. You will receive email reminders for both of these activities throughout your use of your system account. See the troubleshooting guidance in the appendix for help with this.

You will receive notifications prior to the expiration of the password that will contain a link to the system account details page where you can reset the account. You can also sign in to SAM.gov and navigate to your system account details page from your Workspace.

1. Follow the first steps for Getting a System Account API Password to navigate to the system accounts details page. Locate the password section and select either the Reset Password or Forgot Password option.

Administration 46

a. Use Reset Password if you know the current password on the account. Enter your current password, the new password, and confirm the new password. Select Save to complete the process.

Administration 47

b. Use Forgot Password if you do not know the current password on the account. First, select Forgot Password to receive a one-time password (OTP). This will send an email to the signed-in user email.

c. Enter this OTP into the prompt, along with the new password of your choice. Confirm the new password and select Save.

2. Once you receive a success message, your password has been changed and you can use it.

This concludes the information you need to know about system account passwords.

Administration 48

About System Account API Keys API keys allow your system to connect to SAM.gov to send and/or receive data. To connect, you must input a system account API key into the system that you want to connect to SAM.gov. You need to have an active key from your SAM.gov system account in your system at all times so that it can perform the calls that are allowable based on the type connection and rate limits you have. Once you input an API key, it will be good until that key rotates, at which point you must switch out the keys in order to maintain your connection. You can learn more about system account API key rotation cycles in this guide.

Getting a System Account API Key

If this is a new system account, generate your first API key using the following…