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

# 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"

Python

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']['IdToken']
print(jwt_token)

JavaScript (Node.js)

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.getIdToken().getJwtToken();
        console.log(jwtToken);
    },
    onFailure: (error) => {
        console.error(error);
    }
});

JavaScript (React.js)

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 id_token = data.id_token;

      // Store the access token in state or a context for later use
      setToken(id_token);
    } 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;

Native iOS (Swift)

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.idToken?.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 [e-mail] 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>

200 Athletes successfully retrieved

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

404: Not Found No athletes found for the organization

{
    "message": "String type - this will contain more details about the problem encountered"
}

500: Internal Server Error Endpoint request timed out

{
    "message": "String type - this will contain more details about the problem encountered"
}

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

# 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}"

Python

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")

JavaScript (Node.js)

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);
  });

JavaScript (React.js)

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;

Native iOS (Swift)

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()
        }
    }
}