Skip to content

Verify API Endpoint

Use this endpoint to verify a Gridy challenge authentication code.

Verify

Verify a Gridy ID MFA challenge authentication code.

/v1/svc/verify Try it Out


Requests

1. Verify Authentication code.

Verify a Gridy MFA challenge authentication code.

Request Body
type required default desc
idStringfalseYour own internal ref id (max 25 chars)
utctimeStringtrueUTC Time in Milliseconds
apiuserStringtrueYour 9-digit Gridy API UserID
typeinttrue170170 - Verify Gridy Auth Code
bodyStringtrueJson Request body
gridyUserStringtrueUser email address (max 125 chars)
challengeIdStringtrue Gridy MFA Challenge ID
authCodeStringtrue User submitted authentication code
Example
{ 
 "id":< Your own reference >,
 "utctime": "<UTC Timestamp in Milliseconds>",
 "apiUser": "<Your Api User ID>",
 "type":170,
 "body":{
   "gridyUser": "<User Email Address>",
   "challengeId":<User Gridy Challenge ID>,
   "authCode":"<User Input Auth Code>",
 }
}
Sample Code
    curl -X POST "https://api.gridy.io/v1/svc/verify" 
        -H  "accept: application/json; charset=utf-8" 
        -H  "Authorization: gridy-hmac: apiuser=<Your API User ID>,signedheaders=x-gridy-utctime;x-gridy-cnonce,algorithm=gridy-hmac512,signature=e0025d840dc5368028a90a9e73df67fd520e697254de5f4c956e87afdefd56e455eecf549800ee196738f61e83d07d284dda04253e1a4c33ec68f150b6b5faa5" 
        -H  "x-gridy-apiuser: <Your API User ID>" 
        -H  "x-gridy-utctime: <UTC Timestamp in Milliseconds>"  #Use date "+%s" on Unix like OS's to generate
        -H  "x-gridy-cnonce: <Universally Unique ID (UUID v4)>" #Use uuidgen on Unix like OS's to generate 

        -H  "Content-Type: application/json; charset=utf-8" 
        -d "{            
            "id": "<Your own reference>",
            "utctime": "<UTC Timestamp>",
            "apiUser": "< Your Api User ID >",
            "type":170,
            "body":{
                "gridyUser": "demo@gridy.io",
                "challengeId":"<User ChallengeID>",
                "authCode":"<User Input Auth Code>",
                   }    
            }"

  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_AUTHCODE )
            .body( new VerifyRequest.Builder()                      
                .forUser( "<USER EMAIL ADDRESS>" )
                .withId( "<USER GRIDY CHALLENGE ID>")
                .withCode( "<USER SUBMITTED AUTH CODE>")                        
                .build().toJson() 
            );


      try {

        ModelApiResponse result = apiInstance.verify(apiRequest);
        System.out.println(result);

      } catch (ApiException e) {

        System.err.println("Exception when calling GridyIdServiceApi#verify");
        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": 170,
                  "body": {
                        "gridyUser": "demo@gridy.io",
            "challengeId":<Your ChallengeID>,
                        "authCode":"<User Input Auth Code>",    
                    }
              }  # ApiRequest | The JSON body of the request. Contains the Gridy ID verify request.

        try:
            # Verify a Gridy ID MFA authentication code.
            api_response = api_instance.verify(api_request)
            print("The response of GridyIDServiceApi->verify:\n")
            pprint(api_response)
        except ApiException as e:
            print("Exception when calling GridyIDServiceApi->verify: %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_CHALLENGE_VERIFY
        ..apiUser = '000000000'
        ..body = {
                "gridyUser": "demo@gridy.io",
                "challengeId":"<Your ChallengeID>",
                    "authCode":"<User Input Auth Code>"     
        }
        );

    try {
            final response = await api.verify(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->verify: $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":170,
    "body":"{
        "gridyUser":"demo@gridy.io",
        "challengeId":"<Your ChallengeID>",
                    "authCode":"<User Input Auth Code>"     
        }"
    }; // \GridyAPI\Client\Model\ApiRequest | The JSON body of the request. Contains the Gridy ID verify request.

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

} catch (Exception $e) {
        echo 'Exception when calling GridyIDServiceApi->verify: ', $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":170,
     "body":"{
        "gridyUser":"demo@gridy.io",
        "challengeId":"<Your ChallengeID>",
                    "authCode":"<User Input Auth Code>"
           }"
    }; // {ApiRequest} The JSON body of the request. Contains the Gridy ID verify request.

    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 status values (all application-level errors return a HTTP 400 status code)

     
Http Status API Status Description
200OK
3080Gridy Challenge Authentication code Verified successfully
400Bad Request
-1001API User validation error  
-1003API User validation error  
-1026API User permissions error  
-2003Account validation error  
-2004Account blocked  
-2005Account too many failed attempts  
-2006Account locked  
-2007Account disabled  
-2008Account not active  
-2009Account locked  
-2010Account temporarily disabled  
-2017Account lock enabled  
-2038Account lockdown activated  
-2035Challenge cancelled error
-3080Verify auth code match error
-3081Verify auth code expired error
-3082Verify challenge expired error
-3083Verify challenge id match error
-3088Verify challenge already verified error
-3089Verify challenge already authenticated error
-4004HTTP Header x-gridy-utctime missing  
-4005HTTP Header x-gridy-utctime format error  
-4006HTTP Header x-gridy-cnonce missing  
-4007HTTP Header x-gridy-cnonce format error  
-4008HTTP Header x-gridy-apiuser missing error  
-4009HTTP Header x-gridy-apiuser format error  
-4000HTTP Authorization Header missing  
-4001HTTP Authorization Header format error  
-4026HTTP Authorization Header HMAC signature missing
-4027HTTP Authorization Header HMAC signature format error  
-4028HTTP Authorization Header HMAC apiuser missing error  
-4029HTTP Authorization Header HMAC apiuser format error  
-4030HTTP Authorization Header HMAC algorithm missing error  
-4031HTTP Authorization Header HMAC algorithm format error  
-4032HTTP Authorization Header HMAC headers missing error  
-4033HTTP Authorization Header HMAC headers format error  
-4034HTTP Authorization Header HMAC cnonce reused error  
-4035HTTP Authorization Header HMAC timestamp reused error  
-4036HTTP Authorization Header HMAC utctime clock drift error  
-4037HTTP Authorization Header HMAC signature error  
-6021API request blocked - IP address location blocked based on user defined rules
500Internal Error-5000API request rejected due to an Internal error.
Examples
Http Status API Status Description JSON
200OK3080Gridy Challenge Authentication code Verified successfully 
{ 
    "id":< Our reference >,
    "utctime":<UTC Timestamp>,
    "status":200,
    "code":3080,
    "message":"{ 
        "challengeId":"<User Gridy Challenge ID>",
        "verificationCode":"<User Verification Code>",
        "profile":["{ <Assigned Roles & Profiles }"],
        "status":"VERIFIED"
         }"
     }
    "moreinfo":"https://support.gridy.io/status?code=3080" 
}