Quick Start/Overview

Good to know: This is the best way to get started using the Valor API from authorization to making your first request for your desired application.

API Authentication

Your API requests are authenticated using a JWT Bearer token. Any request that doesn't include this token will return an error.

You can obtain the token by providing your Valor username and password along with a provided client_id and user_pool_id:

Note: Contact Valor Biomechanics to obtain the client_id and user_pool_id

# Make the AWS Cognito authentication request using curl
response=$(aws cognito-idp initiate-auth \
  --auth-flow USER_PASSWORD_AUTH \
  --auth-parameters USERNAME=your_username,PASSWORD=your_password \
  --client-id your_client_id)

# Extract the JWT token from the JSON response
jwt_token=$(echo "$response" | jq -r '.AuthenticationResult.IdToken')

# Print the JWT token
echo "JWT Token: $jwt_token"

API Protocols and Headers

The Valor API uses only GET requests to retrieve data and HTTP response codes to communicate request status and errors. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

The Valor API uses a combination of JSON and URL-encoded query parameters to send data to and from the API. When sending JSON data to the API in the request body, the content type of your request must be set to application/json. When receiving data from the API, the content type of your response will always be application/json. All response bodies, including errors, will be sent in JSON format. In the event of an error, the response body will contain details about the error.

API Host

All requests to the Valor API should be made to the following host:

https://487q8d7goe.execute-api.us-east-1.amazonaws.com/production

Errors

The Valor API uses traditional or conventional HTTP response codes to indicate the success or failure of an API request.

In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a provided parameter was invalid, etc.), and codes in the 5xx range indicate an error with the Valor API (these are rare). When possible, the API will also return a JSON response body with additional information about the error.

Code
Name
Description

400

Bad Request Body or Parameters

The gateway response when the request body OR parameter cannot be validated according to an enabled request validator. Accompanying error message should explain in further detail.

401

Unauthorized

The gateway response when the API authorizer failed to authenticate the caller.

403

Access denied, Expired token, Invalid API key, Invalid signature, Missing authentication token, WAF filtered

The gateway response for authentication failure. Accompanying error message should explain in further detail.

404

Resource not found

The gateway response when API cannot find the specified resource after an API request passes authentication and authorization, except for API key authentication and authorization.

413

Request too large

The gateway response for the request too large error.

415

Unsupported media type

The gateway response when a payload is of an unsupported media type, if strict passthrough behavior is enabled.

429

Quota exceeded or Throttled

The gateway response for the usage plan quota exceeded error.

500/504

Internal Server Error

Something is broken. Please contact us at info@bravevirtual.com and let us know what you were trying to do when this error occurred. We will try to get it fixed as soon as possible.

Make your first request

To make your first request, send an authenticated request to the athletes endpoint. This will allow for you to return all athlete objects and their information if needed.

Retrieve athlete(s).

GET https://487q8d7goe.execute-api.us-east-1.amazonaws.com/production/athletes

Obtains all the athletes or a specific athlete within your Valor account.

Query Parameters

Name
Type
Description

athleteID

String

ID of specific athlete for focused search

Headers

Name
Type
Description

Authorization*

String

JWT Bearer Token for authentication: Bearer <JWT token>

{
    "statusCode": 200,
    "body": [{"ValorID": id, "FirstName": first_name, "LastName": last_name},
             {"ValorID": id2, "FirstName": first_name2, "LastName": last_name2},
        ...]
}

The endpoint URL to the API is provided next to the API method (see above)

Take a look at how you might call this method using using the following languages:

# Replace 'your_jwt_token' with the actual JWT token obtained from Cognito
# Replace 'your_limit' and 'your_page' with the desired values for limit and page
jwt_token="your_jwt_token"

# Make a GET request to the API server with JWT token and query string parameters
curl -X GET "your_api_invoke_url_by_path?athleteID=${athleteID}" \
     -H "Authorization: Bearer ${jwt_token}"

Last updated