Authentication and User Authorization

Users looking to use the RCRAInfo API need to register and obtain the necessary permissions for the site they're looking to operate as. For information on registration and permission levels, see the chapter on registration.

After registration, you can use our Pre-production Open API (swagger) page.

API ID and Keys

The system uses a combination of API ID and API key for user authentication and authorization. The API ID and key (credentials) are generated by the RCRAInfo. An API ID/key pair is unique to a user, however the same API ID/key pair is used for all EPA sites that the user has (Site Manager) access to.

Site Managers are the only permission level that can generate API credentials in RCRAInfo. API ID/key pairs do not expire, however keys can be regenerated at any time from within RCRAInfo if the key is lost, compromised, or need to be rotated. An API ID/key pair is terminated is the user account is deactivated or no longer has Site Manager level access for any EPA site. API ID are static.

Security Tokens

The RCRAInfo web services use (Bearer) token authentication. A bearer token is a JSON Web Token (JWT) that is generated by RCRAInfo and is used to authorize users to protected resources. A client must first obtain a security token through the Authentication (auth) service; all requests must send this token in the Authorization header when making requests to protected resources.

An example HTTP request to the federal waste codes service would look like the following...

GET /rcrainfo/rest/api/v1/lookup/federal-waste-codes HTTP/1.1
Host: rcrainfopreprod.epa.gov
Authorization: Bearer theSecurityTokenObtainedFromTheAuthService
Accept: application/json

Token Expirations and Refreshing

The auth service also returns an expiration date-time for the security token. A token expires 20 minutes after creation. Currently, RCRAinfo does not provide refresh tokens or a method to obtain a new tokens without performing a complete authentication (i.e., using the Authentication Service again).

The expiration datetime follows the ISO 8601 profile, the international standard for representing dates and times. Times are expressed in Coordinated Universal Time (UTC) using the time zone offset designator ("+hh:mm") down to the millisecond "expiration": "2023-05-10T19:10:05.923+00:00".

Authenticate Service

Authenticates the user and returns the Security Token. The Security token is used on all subsequent calls and is submitted in the HTTP header using the Authorization in the Key with a value of Bearer.

parameters

  • API ID: API ID generated through the RCRAInfo web application. This is not the user's username.
  • API key: API key generated through the RCRAInfo web application. Keys can be regenerated when necessary.

Examples

Pre-Production

GET /rcrainfo/rest/api/v1/auth/myApiID/myApiKey HTTP/1.1
Host: rcrainfopreprod.epa.gov
Accept: application/json

See also Pre-production Open API (swagger) page

Production

GET /rcrainfoprod/rest/api/v1/auth/myApiID/myApiKey HTTP/1.1
Host: rcrainfo.epa.gov
Accept: application/json


/**
 * Main.java
 * makes a request to the Pre-production Auth endpoint and prints the response to std out
 * open JDK 19
 */
package org.example;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) {
        String baseURL = "https://rcrainfopreprod.epa.gov/rcrainfo/rest/api/v1/auth/";
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(baseURL + "/" + "myApiID" + "/" + "apiKey"))
                .build();
        client.sendAsync(request, HttpResponse.BodyHandlers.ofString())
                .thenApply(HttpResponse::body)
                .thenAccept(System.out::println)
                .join();
    }
}

For a python example, check out the emanifest package on PyPI (source hosted on USEPA/e-manifest repo).

For a TypeScript example, check out the emanifest package on NPM (source hosted in USEPA/e-manifest repo)

Completed Response Example

{
  "token": "eyJhbGciOiJIUzUxMiJ9.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_PGyN6for1GHwf6zqp0OJS10hwK8jEgRyRI0JpFUducwDKj5paWRTEsCky_06pryEve3Yw2w1bbBzqGdSnnw",
  "expiration": "2023-06-23T23:15:45.095+0000"
}

Sequence of Steps

  1. System will check if one of the credentials is empty or incorrect. If so, the following error will be generated:
    • E_SecurityApiInvalidCredentials: Invalid API ID/Key Specified
  2. System will check if API ID was disabled by the Administrator. If so following error will be generated:
    • E_SecurityApiInvalidStatus: API ID Status Invalid
  3. If the System detects 3 unsuccessful attempts for authentication then following error will be generated:
    • E_SecurityApiIDLocked: API ID is locked. If API id was locked the User shall request API ID/API key re-generation
  4. The System will generate JWT and token expiration Date. Security Token contains User Profile and User Role Information in encrypted format. Security Token expiration time is 20 minutes.
  5. If successful the system will return JSON containing following information:
    • token
    • expiration
  6. If failed Authentication the System will return JSON containing the following field:
    • code : Error code which designated for automated processing
    • message: "Human readable" Error message corresponding to the error code
    • errorId: Unique error id for auditing and tracking purpose
    • errorDate: Error Date/Time for auditing and tracking purpose

Errors

CodeMessage
E_SecurityApiInvalidCredentialsInvalid API Id/Key Specified
E_SecurityApiInvalidStatusAPI Id Status Invalid
E_SecurityApiIdLockedAPI Id is Locked
E_SystemErrorMessage describing system error

An example JSON body would contain the following information:

{
  "code": "E_SecurityInvalidCredentials",
  "message": "Invalid API Id was specified.",
  "errorId": "470c188a-82ce-488e-8e85-3e1b71c72ab8",
  "errorDate": "2023-05-11T12:27:59.332+00:00"
}

Security Token Validation

After a security token is obtained, it must be validated before it can be used to access protected resources. The following steps are taken to validate a security token:

  1. The System will validate the Security Token

    1.1 If Web Security Token is invalid, the system stops the submission and generates the following error:

    • E_SecurityApiTokenInvalid: Invalid Security Token

    1.2. If Web Security Token expired, the system stops the submission and generates the following error:

    • E_SecurityApiTokenExpired: Security Token is Expired

    1.3. If Account was inactivated after the token was issued, the system stops the submission and generates the following error:

    • E_SecurityApiInvalidStatus: This API ID is no longer active

User Authorization

The system will perform User Authorization for protected resources afterSecurity Token Validation. Depending on the service, additional user authorization checks may apply (see below).

Base User Authorization

the following checks are performed for all protected resources:

  1. For all requests, the system will perform base user authorization.

    1.1. System will check if the User has Site Manager (Industry) permissions for any Site. If the User does not have permission the System will stop processing and generate the following error:

    • E_IndustryPermissions: The user does not have industry permissions for any Site

  2. The System will validate the Security Token

    1.1 If Web Security Token is invalid, the system stops the submission and generates the following error:

    • E_SecurityApiTokenInvalid: Invalid Security Token

    1.2. If Web Security Token expired, the system stops the submission and generates the following error:

    • E_SecurityApiTokenExpired: Security Token is Expired

    1.3. If Account was inactivated after the token was issued, the system stops the submission and generates the following error:

    • E_SecurityApiInvalidStatus: This API ID is no longer active

Manifest Services User Authorization

  1. For requests include an Image or "DataImage5Copy" submission type, the user must be authorized for the site that is required to submit the manifest to EPA.

    2.1. If rejection = false and user is not authorized for the designatedFacility.epaSiteId, the following error is generated:

    • E_DesignatedFacilityAuthorizationSave: User is not authorized for the Designated Facility. Cannot create Image or DataImage5Copy manifests.

    2.2 If rejection is true, rejectionInfo.transporterOnSite is true, alternateDesignatedFacilityType is "Tsdf" and user is not authorized for rejectionInfo.alternateDesignatedFacility.epaSiteId, the following error is generated:

    • E_AltFacilityAuthorizationSave: User is not authorized for the Alternate Designated Facility. Cannot create Image or DataImage5Copy manifests.

    2.3. If containsPreviousRejectOrResidue is true, additionalInfo.newManifestDestination is OriginalGenerator and user is not authorized for generator.epaSiteId, the following error is generated:

    • E_GeneratorAuthorizationSave: User is not authorized for the Generator. Cannot create Image or DataImage5Copy manifests

  2. If the user is associated with a Broker site and the manifest submission type is "Image", then the System will stop the processing and generates the following error:

    • E_BrokerAuthorizationSave: Brokers are not authorized to create Image manifests

  3. For the Delete, Correct, and Revert services, the system will check if the user has industry permissions for the TSDF, the Generator, or the Alternate TSDF, any of the listed Transporters, of Broker sites on the manifest. If the user does not have permissions, teh system will stop the processing and generate the following error:

    • E_SitePermissions: The user does not have Industry Permissions for either the TSDF Site or Generator Site or Alternate TSDF site, any Transporter site, or Broker site specified in provided JSON