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
curl
Python
JavaScript (Node.js)
JavaScript (React.js)
Native iOS (Swift)
# 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"
import boto3
# Initialize a Cognito Identity Provider client
cognito = boto3.client('cognito-idp', region_name='us-east-1')
# Define user authentication details
username = 'your_username'
password = 'your_password'
client_id = 'your_client_id'
user_pool_id = 'your_user_pool_id'
# Authenticate the user and obtain a JWT token
response = cognito.initiate_auth(
AuthFlow='USER_PASSWORD_AUTH',
AuthParameters={
'USERNAME': username,
'PASSWORD': password,
},
ClientId=client_id,
AuthFlowMetadata={
'UserPoolId': user_pool_id
}
)
# Extract the JWT token from the response
jwt_token = response['AuthenticationResult']['AccessToken']
print(jwt_token)
const AmazonCognitoIdentity = require('amazon-cognito-identity-js');
// Create a user pool object
const poolData = {
UserPoolId: 'your_user_pool_id',
ClientId: 'your_client_id'
};
const userPool = new AmazonCognitoIdentity.CognitoUserPool(poolData);
// Define user authentication details
const authenticationData = {
Username: 'your_username',
Password: 'your_password'
};
// Create a Cognito user object
const authenticationDetails = new AmazonCognitoIdentity.AuthenticationDetails(authenticationData);
const userData = {
Username: 'your_username',
Pool: userPool
};
const cognitoUser = new AmazonCognitoIdentity.CognitoUser(userData);
// Authenticate the user and obtain a JWT token
cognitoUser.authenticateUser(authenticationDetails, {
onSuccess: (session) => {
const jwtToken = session.getAccessToken().getJwtToken();
console.log(jwtToken);
},
onFailure: (error) => {
console.error(error);
}
});
import React, { useState } from 'react';
const YourComponent = () => {
const [username, setUsername] = useState('');
const [password, setPassword] = useState('');
const [token, setToken] = useState('');
const handleLogin = async () => {
try {
const response = await fetch(
'https://your-cognito-endpoint.auth.us-east-1.amazoncognito.com/oauth2/token',
{
method: 'POST',
headers: {
'Content-Type': 'application/x-www-form-urlencoded',
},
body: new URLSearchParams({
grant_type: 'password',
client_id: 'your-client-id',
username: username,
password: password,
}).toString(),
}
);
if (!response.ok) {
throw new Error('Authentication failed');
}
const data = await response.json();
const accessToken = data.access_token;
// Store the access token in state or a context for later use
setToken(accessToken);
} catch (error) {
console.error('Authentication error:', error);
}
};
return (
<div>
<h2>Login</h2>
<input
type="text"
placeholder="Username"
value={username}
onChange={(e) => setUsername(e.target.value)}
/>
<input
type="password"
placeholder="Password"
value={password}
onChange={(e) => setPassword(e.target.value)}
/>
<button onClick={handleLogin}>Login</button>
{token && (
<div>
<h3>JWT Token</h3>
<pre>{token}</pre>
</div>
)}
</div>
);
};
export default YourComponent;
import AWSCognitoIdentityProvider
// Define user authentication details
let username = "your_username"
let password = "your_password"
let userPoolId = "your_user_pool_id"
let clientId = "your_client_id"
// Create a Cognito user pool object
let serviceConfiguration = AWSServiceConfiguration(
region: .USEast1,
credentialsProvider: nil
)
let poolConfiguration = AWSCognitoIdentityUserPoolConfiguration(
clientId: clientId,
clientSecret: nil,
poolId: userPoolId
)
AWSCognitoIdentityUserPool.register(
with: serviceConfiguration,
userPoolConfiguration: poolConfiguration,
forKey: "UserPoolKey"
)
let userPool = AWSCognitoIdentityUserPool(forKey: "UserPoolKey")
// Authenticate the user and obtain a JWT token
let user = userPool.getUser(username)
let authDetails = AWSCognitoIdentityPasswordAuthenticationDetails(
username: username,
password: password,
validationData: nil
)
user?.getSession(
username,
password: password,
validationData: nil
).continueWith { (task) in
if let error = task.error {
print("Authentication error: \(error.localizedDescription)")
} else if let session = task.result {
print("JWT Token: \(session.accessToken?.tokenString ?? "")")
}
return nil
}

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 [email protected] 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.
get
https://487q8d7goe.execute-api.us-east-1.amazonaws.com/production
/athletes
Retrieve athlete(s).
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:
curl
Python
JavaScript (Node.js)
JavaScript (React.js)
Native iOS (Swift)
# 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}"
import requests
# Replace 'your_jwt_token' with the actual JWT token obtained from Cognito
jwt_token = 'your_jwt_token'
url = "your_api_invoke_url_by_path"
# Replace these values with the desired limit and page values
params = {
"athleteID": "your_unique_athlete_ID"
}
headers = {
"Authorization": f"Bearer {jwt_token}"
}
response = requests.get(url, headers=headers, params=params)
if response.status_code == 200:
data = response.json()
# Process the JSON data here
else:
print("Failed to fetch data from the API")
const fetch = require('node-fetch');
// Replace 'your_jwt_token' with the actual JWT token obtained from Cognito
const jwtToken = 'your_jwt_token';
const url = "your_api_invoke_url_by_path";
// Replace these values with the desired limit and page values
const queryParams = new URLSearchParams({
"athleteID": "your_unique_athlete_ID"
});
const headers = {
"Authorization": `Bearer ${jwtToken}`
};
fetch(`${url}?${queryParams}`, { headers })
.then(response => response.json())
.then(data => {
// Process the JSON data here
})
.catch(error => {
console.error("Failed to fetch data from the API:", error);
});
import React, { useEffect, useState } from 'react';
const YourComponent = () => {
const [data, setData] = useState([]);
// Replace 'your_jwt_token' with the actual JWT token obtained from Cognito
const jwtToken = 'your_jwt_token';
// Replace these values with the desired limit, page, or athleteID values
const athleteID = "your_unique_athlete_ID";
useEffect(() => {
const fetchData = async () => {
try {
const queryParams = new URLSearchParams({
"athleteID": athleteID
});
const response = await fetch(`your_api_invoke_url_by_path?${queryParams}`, {
headers: {
"Authorization": `Bearer ${jwtToken}`
}
});
if (response.ok) {
const jsonData = await response.json();
setData(jsonData);
} else {
console.error("Failed to fetch data from the API");
}
} catch (error) {
console.error("Error fetching data:", error);
}
};
fetchData();
}, []);
return (
<div>
{/* Render the fetched data here */}
</div>
);
};
export default YourComponent;
import SwiftUI
struct AthleteData: Codable {
// Define your data model here to match the API response structure
}
struct ContentView: View {
@State private var data: AthleteData?
// Replace 'your_jwt_token' with the actual JWT token obtained from Cognito
let jwtToken = "your_jwt_token"
// Replace with the desired athleteID
let athleteID = "your_unique_athlete_id"
var body: some View {
VStack {
// Render the fetched data here
}
.onAppear() {
fetchData()
}
}
func fetchData() {
var urlComponents = URLComponents(string: "your_api_invoke_url_by_path")!
urlComponents.queryItems = [
URLQueryItem(name: "athleteID", value: String(athleteID))
]
let url = urlComponents.url!
var request = URLRequest(url: url)
request.setValue("Bearer \(jwtToken)", forHTTPHeaderField: "Authorization")
URLSession.shared.dataTask(with: request) { (data, _, _) in
if let data = data {
do {
let decoder = JSONDecoder()
let decodedData = try decoder.decode(AthleteData.self, from: data)
self.data = decodedData
} catch {
print("Error decoding data:", error)
}
}
}.resume()
}
}
@main
struct YourApp: App {
var body: some Scene {
WindowGroup {
ContentView()
}
}
}