Status API Endpoint

Use this endpoint to check a Gridy MFA challenge status.

Status

Check a Gridy ID MFA challenge status.

/v1/svc/status

Try it Out

Requests

1. Check Status.

Check a Gridy MFA challenge status.

Request Body

		type	required	default	desc
id		String	false		Your own internal ref id (max 25 chars)
utctime		String	true		UTC Timestamp in Milliseconds
apiuser		String	true		Your 9-digit Gridy API UserID
type		int	true	171	171 - New Status Check
body		String	true		Json Request body
	gridyUser	String	true		User Email address (max 125 chars)
	challengeId	String	true		Gridy MFA Challenge ID

Example

{ 
 "id":<Your own reference>,
 "utctime": <UTC Timestamp> ,
 "apiUser":<Your Api User ID>,
 "type":171,
 "body":{
   "gridyUser": "<User Email Address>",
   "challengeId":<User Gridy Challenge ID>,
 }
}

Sample Code

cURLJavaPythonDartPHPJS

    curl -X POST "https://api.gridy.io/v1/svc/status" 
        -H  "accept: application/json; charset=utf-8" 
        -H  "Authorization: gridy-hmac: apiuser=000000000,signedheaders=x-gridy-utctime;x-gridy-cnonce,algorithm=gridy-hmac512,signature=e0025d840dc5368028a90a9e73df67fd520e697254de5f4c956e87afdefd56e455eecf549800ee196738f61e83d07d284dda04253e1a4c33ec68f150b6b5faa5" 
        -H  "x-gridy-apiuser: 000000000" 
        -H  "x-gridy-utctime: 1734732919817" 
        -H  "x-gridy-cnonce: 8dcb623a-b56e-4534-838b-5e9e" 
        -H  "Content-Type: application/json; charset=utf-8" 
        -d "{            
            "id":< Your own reference >,
            "utctime": <UTC Timestamp>,
            "apiUser":< Your Api User ID >,
            "type":171,
            "body":{
                "gridyUser": "<User Email Address>",
                "challengeId":<User Gridy ChallengeID>
                   }    
            }"

      import io.gridy.client.ApiClient;
  import io.gridy.client.ApiException;
  import io.gridy.client.Configuration;
  import io.gridy.client.auth.HmacSha512Auth;
  import io.gridy.client.model.*;
  import io.gridy.client.api.GridyIdServiceApi

  ApiClient defaultClient = new ApiConfig.Builder()
             # Configure API User Id
            .withApiUser( System.getEnv("GRIDY_API_USER")  )
             # Configure API User Secret
            .withApiSecret( System.getEnv("GRIDY_API_SECRET")  )
             # Configure API Environment
            .withApiEnv(GridyEnv.LIVE)
            .build();       

      GridyIdServiceApi apiInstance = new GridyIdServiceApi(defaultClient);
      ApiRequest apiRequest = new ApiRequest()
            .id("YOUR ID REFERENCE")
            .apiUser( defaultClient.getApiUser() )
            .type( ApiReqstType.VERIFY_CHECKSTATUS )
            .body( new StatusRequest.Builder()                      
                .forUser( "<USER EMAIL ADDRESS>" )
                .withId( "<USER GRIDY CHALLENGE ID>")  
                .build().toJson() 
            )


      try {
        ModelApiResponse result = apiInstance.status(apiRequest);
        System.out.println(result);

      } catch (ApiException e) {

        System.err.println("Exception when calling GridyIdServiceApi#status");
        System.err.println("Status code: " + e.getCode());
        System.err.println("Reason: " + e.getResponseBody());
        System.err.println("Response headers: " + e.getResponseHeaders());

        e.printStackTrace();
}

    import gridyapi_client
    from gridyapi_client.rest import ApiException
    from pprint import pprint

    # Defining the host is optional and defaults to https://api.gridy.io
    # See configuration.py for a list of all supported configuration parameters.
    configuration = gridyapi_client.Configuration(
            host="https://api.gridy.io"
    )

    # The client must configure the authentication and authorization parameters
    # in accordance with the API server security policy.

    # Configure API User Id
    configuration.api_user = os.environ["GRIDY_API_USER"]

    # Configure API User Secret
    configuration.api_secret = os.environ["GRIDY_API_SECRET"]

    # Enter a context with an instance of the API client
    with gridyapi_client.ApiClient(configuration) as api_client:

        # Create an instance of the API class
        api_instance = gridyapi_client.GridyIDServiceApi(api_client)
        api_request = {
                  "id": < Your own reference >,
                  "utctime": "",
                  "apiUser": 000000000,
                  "type": 150,
                  "body": {
                        "gridyUser": "<User Email Address>",
            "challengeId":<User Gridy Challenge ID>,    
                       }
              }  # ApiRequest | The JSON body of the request. Contains the Gridy ID status request.

        try:
            # Send or Cancel a Gridy ID MFA status request.
            api_response = api_instance.status(api_request)
            print("The response of GridyIDServiceApi->status:\n")
            pprint(api_response)
        except ApiException as e:
            print("Exception when calling GridyIDServiceApi->status: %s\n" % e)

    import 'package:gridy_mfa_client/gridyapi.dart';

    final api = GridyClient()
        .setHmacAuth('<Your 9-digit API User ID>','<Your API Secret Key>')
        .getGridyIDServiceApi();

        ApiRequest request = ApiRequest( (r) =>
        r
        ..id = 'Your refernence ID'
        ..utcTime = DateTime.now()
            .toUtc().millisecondsSinceEpoch
            .toString()
        ..type = API_STATUS_CHECK
        ..apiUser = '<Your API User ID>'
        ..body = {
                "gridyUser": '<User Email Address>',
                "challengeId":'<User Gridy Challenge ID>',
        }
        );

    try {
            final response = await api.status(apiRequest);
            final _dresponse = ApiResponse( (r) =>
            r
             ..id = _response.data?.id
             ..utcTime = _response.data?.utcTime
             ..status = _response.data?.status
             ..message = _response.data?.message
             ..code = _response.data?.code
             ..moreInfo = _response.data?.moreInfo
              );

            print(response);

    } catch on DioException (e) {
            print("Exception when calling GridyIDServiceApi->status: $e\n"); 
    }

require_once(__DIR__ . '/vendor/autoload.php');

// Configure Your Gridy API User ID
$config = GridyAPI\Client\Configuration::getDefaultConfiguration()->setApiUser( 'YOUR_API_USER_ID');

// Configure Your Gridy API Secret Key
$config = GridyAPI\Client\Configuration::getDefaultConfiguration()->setApiUser( 'YOUR_API_SECRET_KEY');


$apiInstance = new GridyAPI\Client\Service\GridyIDServiceApi(
        // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
        // This is optional, `GuzzleHttp\Client` will be used as default.
        new GuzzleHttp\Client(),
        $config
);

$api_request = { 
    "id":< Your own reference >,
    "utctime": <UTC Timestamp>,
    "apiUser":000000000,
    "type":150,
    "body":{
        "gridyUser":"demo@gridy.io",
        "challengeId":<User ChallengeID>,
        }
    }; // \GridyAPI\Client\Model\ApiRequest | The JSON body of the request. Contains the Gridy ID challenge request.

try {
        $result = $apiInstance->challenge($api_request);
        print_r($result);

} catch (Exception $e) {
        echo 'Exception when calling GridyIDServiceApi->challenge: ', $e->getMessage(), PHP_EOL;
}

    var GridyIdApi = require('gridy_client');
    var defaultClient = GridyIdApi.ApiClient.instance;
    var api = new GridyIdApi.GridyIDServiceApi()

    var apiRequest = { 
     "id":< Your own reference >,
     "utctime": <UTC Timestamp>,
     "apiUser":000000000,
     "type":150,
     "body":{
        "gridyUser":"demo@gridy.io",
        "challengeId":<User ChallengeID>,
     }
    var callback = function(error, data, response) {
        if (error) {
                console.error(error);
        } else {
                console.log('API called successfully. Returned data: ' + data);
        }
    };

    api.challenge(apiRequest, callback);

Postman Collection

Don't want to write code? Check out the Gridy Postman Collection or the API Explorer for a no-code way to get started with Gridy's API.

Responses

All responses are JSON, with errors indicated in response bodies as negative integer status values (all application-level errors return a HTTP 400 status code)

Http Status		API Status	Description
200	OK	3090	Gridy MFA Challenge completed successfully
204	No Content	-3091	Gridy MFA challenge status still pending
400	Bad Request
		-1001	API User validation error
		-1003	API User validation error
		-1026	API User permissions error
		-2003	Account validation error
		-2004	Account blocked
		-2005	Account too many failed attempts
		-2006	Account locked
		-2007	Account disabled
		-2008	Account not active
		-2009	Account locked
		-2010	Account temporarily disabled
		-2017	Account lock enabled
		-2038	Account lockdown activated
		-2035	Challenge cancelled error
		-3080	Verify auth code match error
		-3081	Verify auth code expired error
		-3082	Verify challenge expired error
		-3083	Verify challenge id match error
		-3088	Verify challenge already verified error
		-3089	Verify challenge already authenticated error
		-4004	HTTP Header x-gridy-utctime missing
		-4005	HTTP Header x-gridy-utctime format error
		-4006	HTTP Header x-gridy-nonce missing
		-4007	HTTP Header x-gridy-nonce format error
		-4008	HTTP Header x-gridy-apiuser missing error
		-4009	HTTP Header x-gridy-apiuser format error
		-4000	HTTP Authorization Header missing
		-4001	HTTP Authorization Header format error
		-4026	HTTP Authorization Header HMAC signature missing
		-4027	HTTP Authorization Header HMAC signature format error
		-4028	HTTP Authorization Header HMAC apiuser missing error
		-4029	HTTP Authorization Header HMAC apiuser format error
		-4030	HTTP Authorization Header HMAC algorithm missing error
		-4031	HTTP Authorization Header HMAC algorithm format error
		-4032	HTTP Authorization Header HMAC headers missing error
		-4033	HTTP Authorization Header HMAC headers format error
		-4034	HTTP Authorization Header HMAC nonce reused error
		-4035	HTTP Authorization Header HMAC timestamp reused error
		-4036	HTTP Authorization Header HMAC utctime clock drift error
		-4037	HTTP Authorization Header HMAC signature error
		-6021	API request blocked - IP address location blocked based on user defined rules
404	Not Found	-3090	Gridy MFA Challenge does not exist
500	Internal Error	-5000	API request rejected due to an Internal error.

Examples

Http Status API Status Description JSON

204

No Content

-3091

Gridy Challenge Verification Still Pending

{
 "id":"FJYTN1717753767207"  
 "utctime":"2024-06-07T09:49:27.283871Z"
 "status":204                 
 "code":-3091               
 "message": "NO CONTENT :- CHALLENGE VERIFICATION STILL PENDING"
 "more info":"https://support.gridy.io/errors?code=-3091"
}