Authentication

Tagshelf uses three mechanisms of authentication to allow access to the API: OAuth, HMAC and API key.

OAuth

OAuth is an open standard for access delegation commonly used as a way for Internet users to grant websites or applications access to their information on other websites without giving them the passwords. It allows for token-based authentication and authorization.

Best Usage Scenarios

• Integrated Web Portals: OAuth is ideal for situations where you have a web portal that needs to integrate with a document parser or other API-driven services. It's especially suited for services that users access through a web browser.

• Ephemeral Browser Sessions: Given that browser sessions are typically short-lived and users are accustomed to logging in frequently, OAuth is a good fit for web applications where users expect to authenticate periodically.

• Secured, Scoped Access: If you need to provide access to specific functionalities or data without exposing user credentials, OAuth tokens enable this level of granularity and security.

Benefits

• Enhanced Security: By using tokens instead of credentials for each request, OAuth reduces the risk of credential exposure.

• Flexibility: OAuth tokens can be scoped to limit access to specific actions or data, enhancing security and control over what third-party applications can do.

• User Experience: OAuth aligns with user expectations for web applications, where periodic re-authentication is standard and doesn't detract from the experience.

• Token Expiration: The default expiration of tokens (typically one month) balances security with convenience, reducing the need for frequent re-authentications while maintaining a reasonable security posture.

Best Practices

• Secure Token Storage: Ensure that OAuth tokens are stored securely on the client side, as they essentially act as a stand-in for user credentials.

• Handle Token Expiration Gracefully: Implement logic in your application to handle token expiration smoothly, prompting users to re-authenticate when necessary.

Obtain OAuth Access Token

POST https://<env>.tagshelf.com/token

The /token endpoint is designed for obtaining OAuth access tokens through a direct user authentication process. Users provide their credentials (username and password) to receive a bearer token, which is then used for authorizing subsequent API requests. This endpoint uses the OAuth 2.0 password grant type, making it suitable for scenarios where applications require user credentials to grant access tokens. The request is made via a POST method with URL-encoded body parameters, including grant_type, username, and password. The successful response includes the access token along with its type, expiration details, and the authenticated username. This endpoint is essential for initiating secure, token-based user sessions in the API.

Headers

Name	Type	Description
Content-Type*	String	application/x-www-form-urlencoded

Request Body

Name	Type	Description
grant_type*	String	Must be set to password. This parameter specifies the type of OAuth grant being requested.
password*	String	The corresponding password for the user.
username*	String	The username of the user attempting to authenticate.

200: OK A 200 OK response from the /token endpoint indicates successful authentication and token issuance. This response confirms that the user's credentials are valid, and an access token has been generated for use in subsequent API requests.

{
  "access_token": "qW-TI5C1En4VH_EtZBZXFtPvUEJ-dzm-4X7Qb3eu58d5iXMHisdqGow2tHb5EvgmRKIgDBz1NMtzrFNOKzRzir3ZGB5nLXpfN0DfwiP5msoD5ns2YRKPKWVKjSDZQIPOtyWdYBteO5doH22b6wUFgy1HHn4pdpMihBocg1hwd5wQX7YmxEgOblT9sLuUAKqY3y-Qu6VOiJRSjQ4V3LDfrojVhzqMXDK3QvhZYSQ2nWoILB0A-NriuQbpmzXgxPP2q_R9wE_98rubEhUvW_0MwMFqaKwyIt1cPqskBy1UgdDvqJRcQUfq1v8yPE4WwBlW8mqLKPPSiCuAsG_1fB-0tqOfHU0BtDPPJ15ko1u6zJGMIZKZGn9XbCSU-a3iurbPmQK4NdmErT_wTjwpiH__ZNt0E9q6YhzyawEhBU1uL_F5rdmzZvTNZoB1xlUol2nASf0nQDeZqsD1ehBWeb2NrTGafST32Vfa6xVy_HpU4PH0vGLN5L-dEvbo5gl4z1KdDC7ZlKZGSfcderzh8_fAaFJ9vrL0jnffVb-sqLhsRh7_SdIn-43zl5EzbYjjyCDTwyPOnNppH7PGLoO8uLZPFDY1LBo_-T6IGzXPlFVwjgsa-YSTd37qKFlPPHMYa0Dm",
  "token_type": "bearer",
  "expires_in": 1209599,
  "userName": "[e-mail]",
  ".issued": "Fri, 10 Aug 2018 14:50:42 GMT",
  ".expires": "Fri, 24 Aug 2018 14:50:42 GMT"
}

Once you get a successful response, you would need to pass the returned access token as the value of the Authorization header field with the Bearer prefix.

HMAC

HMAC, which will require for you to provide authentication signature per request.

In cryptography, an HMAC is a specific type of message authentication code involving a cryptographic hash function and a secret cryptographic key. As with any MAC, it may be used to simultaneously verify both the data integrity and the authenticity of a message.

There are some notable differences with OAuth: The authentication signature is different per every request. You would be using a secret key and an api key to generate the signature. The secret key will never change, and the api key will only change if you explicitly do it over your user profile page.

The signature should by passed as a value of the Authorization header field with the amx prefix.

Ideal when:

• Handling Individual Account Access: HMAC is particularly suitable for applications requiring individual account access without the need for managing token expiration.

• Ensuring Secure Transactions: It provides a secure method for authenticating API requests, ensuring the authentication and integrity of each request.

---

Signature Structure

var hmacKey = "amx " + <secret> + ":" + <requestSignatureBase64String> + ":" + <nonce> + ":" + <requestTimeStamp>;

Example Pseudocode of a function to generate the key

Function GenerateSignature(data, secretKey):
    // Initialize HMAC with the secret key and chosen hash function (e.g., SHA256)
    hmac = InitializeHMAC(secretKey, HashFunction)

    // Add the data to the HMAC
    hmac.update(data)

    // Generate the final HMAC signature
    signature = hmac.finalize()

    // Encode the signature in a desired format (e.g., hexadecimal or base64)
    encodedSignature = Encode(signature, EncodingFormat)

    Return "amx " + encodedSignature

## Resulting in a string
Authorization: amx 123456:ABcdE1FgHiJkLmNoPqRStuVWXyz23/4abcDe+fGHi==:xyz789:1615237062

In our efforts to streamline the API integration process for our users, we've included a pre-request script in our Postman collection.

This script is specially designed to generate the HMAC signature automatically, simplifying the authentication process. By utilizing this feature, API users can efficiently manage authentication signatures for each request, ensuring secure and seamless access to our services. This pre-request script not only enhances the user experience but also serves as a valuable reference point for understanding and implementing HMAC authentication in their applications. To access and utilize this feature, users can download our Postman collection from here.

This inclusion underscores our commitment to providing accessible and user-friendly tools, facilitating a more efficient integration of our API into various applications and services.

---

Best Practices

• Secure Key Management: Ensure cryptographic keys are securely stored and managed.

• Include Timestamps: Implement timestamps in the signature to help prevent replay attacks.

• Dynamic Nonce: Generate a unique nonce for each request to enhance security.

API key

The API Key is a secure and straightforward authentication method, ideally suited for server-to-server communication where interactive user authentication is not feasible, such as in unattended production applications.

This method, which we strongly recommend for automated processes or services that require consistent access to the API without manual intervention, ensures a high level of security and operational efficiency. API keys, acting as unique identifiers for applications, can be easily generated, managed, and invalidated through the company's applications admin panel.

By including these keys in the HTTP header of each API request, they provide a non-interactive yet robust way to authenticate and control access, simplifying the process significantly while maintaining the security integrity of the API interactions. The API key should be included in each API request's HTTP header. Use the key X-TagshelfAPI-Key to pass the API key value.

Benefits

• Non-Interactive Authentication: Ideal for scenarios where interactive user authentication is impractical or impossible, such as background services or automated tasks.

• Simplicity and Security: Provides a straightforward yet secure way of authenticating requests, avoiding the complexity of more interactive methods like OAuth.

• Easy to Control Access: API keys can be easily created, rotated, and revoked, giving administrators full control over access to the API.

Best Practices

• Secure Storage of API Keys: Store API keys securely on the server. They should never be exposed in client-side code or public repositories.

• Limit Access and Permissions: Apply the principle of least privilege by limiting what each API key can access and perform within the API.

• Regular Rotation: Regularly rotate API keys to reduce the risk of compromise.

While API keys are a secure method of authentication, they should be treated with the same level of security as passwords. Compromised keys can allow unauthorized access to your API, so it's crucial to manage them carefully and follow security best practices.